플랫폼 어댑터 추가

기준일: 2026-07-26
난이도: 중급
공식 기준: Adding a Platform Adapter

개요

Hermes Messaging Gateway에 새 플랫폼 어댑터를 추가하는 방법입니다. 권장 경로는 플러그인(plugins/platforms/)이며, 코어 빌트인 경로는 유지보수 비용이 큽니다.

핵심 개념

개념	설명
Plugin adapter	코어 수정 없이 플랫폼 추가
Built-in adapter	enum/config/runner 배선 필요
YAML→env bridge	설정 값을 env 계약으로 투영
Cron delivery	스케줄 결과 플랫폼 전달
Slow-LLM UX	typing/keepalive 패턴

상세

아키텍처 개요

원문 절: Architecture Overview

• connect()
• disconnect()
• send()
• send_typing()
• get_chat_info()

User ↔ Messaging Platform ↔ Platform Adapter ↔ Gateway Runner ↔ AIAgent

플러그인 경로 (권장)

원문 절: Plugin Path (Recommended)

• plugin.yaml — 공식 하위 절. 구현·설정 세부 원문 참조.
• adapter.py — 공식 하위 절. 구현·설정 세부 원문 참조.
• Configuration — 공식 하위 절. 구현·설정 세부 원문 참조.
• What the Plugin System Handles Automatically — 공식 하위 절. 구현·설정 세부 원문 참조.

Integration point	How it works
Gateway adapter creation	Registry checked before built-in if/elif chain
Config parsing	Platform._missing_() accepts any platform name
Connected platform validation	Registry validate_config() called
User authorization	allowed_users_env / allow_all_env checked
Env-only auto-enable	env_enablement_fn seeds PlatformConfig.extra + home_channel
YAML config bridge	apply_yaml_config_fn translates config.yaml keys into env vars / extras
Cron delivery	cron_deliver_env_var makes deliver=<name> work
hermes config UI entries	requires_env / optional_env in plugin.yaml auto-populate
send engine (tools/send_message_tool.py)	Routes through live gateway adapter
Webhook cross-platform delivery	Registry checked for known platforms
/update command access	allow_update_command flag
Channel directory	Plugin platforms included in enumeration
System prompt hints	platform_hint injected into LLM context
Message chunking	max_message_length for smart splitting
PII redaction	pii_safe flag
hermes status	Shows plugin platforms with (plugin) tag
hermes gateway setup	Plugin platforms appear in setup menu
hermes tools / hermes skills	Plugin platforms in per-platform config
Token lock (multi-profile)	Use acquire_scoped_lock() in your connect()
Orphaned config warning	Descriptive log when plugin is missing

~/.hermes/plugins/my-platform/
  plugin.yaml      # Plugin metadata
  adapter.py       # Adapter class + register() entry point

환경변수 기반 자동 설정

원문 절: Env-Driven Auto-Configuration

• before

YAML→env 설정 브리지

원문 절: YAML→env Config Bridge

• platform-specific

Cron 전달

원문 절: Cron Delivery

• Out-of-process cron delivery — 공식 하위 절. 구현·설정 세부 원문 참조.

ctx.register_platform(
    name="my_platform",
    ...
    cron_deliver_env_var="MY_PLATFORM_HOME_CHANNEL",
)

hermes config에 env 노출

원문 절: Surfacing Env Vars in hermes config

• Supported dict keys:

플랫폼별 느린 모델 UX

원문 절: Platform-Specific Slow-LLM UX

• Pattern: subclass _keep_typing to layer mid-flight UX — 공식 하위 절. 구현·설정 세부 원문 참조.
• Pattern: subclass send to route through a cache instead of sending immediately — 공식 하위 절. 구현·설정 세부 원문 참조.
• When this pattern is appropriate — 공식 하위 절. 구현·설정 세부 원문 참조.
• Reference Implementation — 공식 하위 절. 구현·설정 세부 원문 참조.
• Reference Implementations (Plugin Path) — 공식 하위 절. 구현·설정 세부 원문 참조.
• Pending postback active for this chat

async def send(self, chat_id: str, content: str, **kw) -> SendResult:
    if _is_system_bypass(content):
        return await self._send_text_chunks(chat_id, content, force_push=False)
    pending_rid = self._pending_buttons.get(chat_id)
    if pending_rid:
        self._cache.set_ready(pending_rid, content)
        return SendResult(success=True, message_id=pending_rid)
    return await self._send_text_chunks(chat_id, content, force_push=False)

빌트인 경로 단계 체크리스트

원문 절: Step-by-Step Checklist (Built-in Path)

• 1. Platform Enum — 공식 하위 절. 구현·설정 세부 원문 참조.
• 2. Adapter File — 공식 하위 절. 구현·설정 세부 원문 참조.
• 3. Gateway Config (gateway/config.py) — 공식 하위 절. 구현·설정 세부 원문 참조.
• 4. Gateway Runner (gateway/run.py) — 공식 하위 절. 구현·설정 세부 원문 참조.
• 5. Cross-Platform Delivery — 공식 하위 절. 구현·설정 세부 원문 참조.
• 6. CLI Integration — 공식 하위 절. 구현·설정 세부 원문 참조.

File	What to add
website/docs/user-guide/messaging/newplat.md	Full platform setup page
website/docs/user-guide/messaging/index.md	Platform comparison table, architecture diagram, toolsets table, security section, next-steps link
website/docs/reference/environment-variables.md	All NEWPLAT_* env vars
website/docs/reference/toolsets-reference.md	hermes-newplat toolset
website/docs/integrations/index.md	Platform link
website/sidebars.ts	Sidebar entry for the docs page
website/docs/developer-guide/architecture.md	Adapter count + listing
website/docs/developer-guide/gateway-internals.md	Adapter file listing

class Platform(str, Enum):
    # ... existing platforms ...
    NEWPLAT = "newplat"

Parity Audit

• 이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

# Find every .py file mentioning the reference platform
search_files "bluebubbles" output_mode="files_only" file_glob="*.py"

# Find every .py file mentioning the new platform
search_files "newplat" output_mode="files_only" file_glob="*.py"

# Any file in the first set but not the second is a potential gap

Common Patterns

• Long-Poll Adapters — 공식 하위 절. 구현·설정 세부 원문 참조.
• Callback/Webhook Adapters — 공식 하위 절. 구현·설정 세부 원문 참조.
• Token Locks — 공식 하위 절. 구현·설정 세부 원문 참조.

async def connect(self):
    self._poll_task = asyncio.create_task(self._poll_loop())
    self._mark_connected()

async def _poll_loop(self):
    while self._running:
        messages = await self._fetch_updates()
        for msg in messages:
            await self.handle_message(self._build_event(msg))

Reference Implementations

• 이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Adapter	Pattern	Complexity	Good reference for
bluebubbles.py	REST + webhook	Medium	Simple REST API integration
weixin.py	Long-poll + CDN	High	Media handling, encryption
wecom_callback.py	Callback/webhook	Medium	HTTP server, AES crypto, multi-app
plugins/platforms/irc/adapter.py	Long-poll + IRC protocol	High	Full-featured plugin adapter with scoped token lock

체크리스트

• 공식 원문 Adding a Platform Adapter과 대조했다
• 관련 코드·설정·권한을 로컬에서 확인했다
• 보안·opt-in·allowlist 정책을 지켰다
• 스모크 테스트 또는 단계 검증을 수행했다

다음 단계

• 공식 문서: Adding a Platform Adapter
• Hermes Agent 소개
• 트러블슈팅

---

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스