Secret Source الإضافات
Secret Source Plugins
ابدأ بالمعنى، ثم انتقل إلى التفاصيل.
هذا الدرس يشرح Secret Source الإضافات ضمن موضوع داخل Hermes وكيف يوسّعه المطور. ستعرف ما الذي يفعله هذا الجزء، متى تحتاجه، وما أصغر خطوة آمنة للتأكد أنه يعمل.
إن كنت جديدًا: لا تحفظ الأسماء. ركّز على ثلاثة أسئلة: ما المشكلة التي يحلها هذا الجزء؟ ما البيانات أو الصلاحيات التي يحتاجها؟ وكيف أعرف أن النتيجة صحيحة؟
للتطبيق: اقرأ المثال الأول، حدّد ما سيغيّره، نفّذه على بيانات تجريبية، ثم قارن الناتج بما وعد به المصدر.
للمتخصص: راجع What the framework owns vs. what you own، Directory structure، The SecretSource ABC، ثم افحص حالات الفشل والتوافق مع إصدارك.
اعرف Python وGit وبنية مشروع برمجي قبل تعديل الكود.
نتيجة واضحة قبل أن تقرأ.
- تفهم Secret Source الإضافات من دون افتراض معرفة سابقة.
- تفرّق بين الوصف والمعلومة التي تحتاج إلى اختبار في بيئتك.
- اقرأ الأمر الأول وحدد المدخلات والمخرجات قبل نسخه.
How to build a secret-manager backend plugin for Hermes Agent
ما الذي يقوله المصدر، وبأي ترتيب؟
- 01What the framework owns vs. what you own
ابدأ بهذا القسم لتفهم الفكرة أو البنية الأساسية.
- 02Directory structure
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 03The SecretSource ABC
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 04Contract rules (enforced, not suggestions)
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 05Choosing your shape
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 06Optional hooks
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 07Subprocess safety: use runsecretcli()
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 08Registering
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 09Users configure it like any other source
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
- 10Validate with the conformance kit
اختم بهذا القسم لتفحص النتيجة والحالات الخاصة.
انسخ بعد أن تفهم الأثر.
~/.hermes/plugins/my-vault/
├── plugin.yaml # name, description
└── __init__.py # SecretSource subclass + register(ctx)### Contract rules (enforced, not suggestions)
- **`fetch()` never raises.** Errors go in `result.error` + `result.error_kind`. A raising fetch is contained by the orchestrator and reported as `INTERNAL` — a contract violation, not a feature.
- **`fetch()` never prompts.** Startup runs in non-TTY contexts (gateway, cron, Docker). `run_secret_cli()` closes stdin so a prompting helper fails fast. Interactive auth belongs in your CLI setup flow, never on the startup path.
- **Sync, within budget.** The orchestrator enforces a wall-clock timeout (default 120s, user-tunable via `secrets.<name>.timRegistration is rejected (with a log warning, never a crash) for: non-`SecretSource` instances, invalid/duplicate names, a `scheme` another source owns, wrong `api_version`, or a `shape` outside `mapped`/`bulk`.
:::note Timing
Plugin discovery runs later in startup than the first `load_hermes_dotenv()` call, so a plugin source is not consulted by the very first env load of the process that discovers it. It IS consulted by every subsequently spawned Hermes process (gateway children, cron sessions, subagents). Bundled sources cover first-process bootstrap.
:::
## Users configure it like any otاقرأ الأمر الأول وحدد المدخلات والمخرجات قبل نسخه.
طابق أي أمر مع إصدار Hermes المثبّت، وراجع الملفات والحسابات التي قد يصل إليها، واستخدم بيانات غير حساسة في أول اختبار. إذا اختلف الشرح عن المصدر، فالمصدر الرسمي هو المرجع النهائي.