Documentation Sync

This page is auto-generated from plugins/adapters/milky/README.md. Please edit the in-package README and then run pnpm sync:adapter-docs.

@zhin.js/adapter-milky

Zhin.js Milky protocol adapter (Plugin Runtime). Default is forward WebSocket client (connection: ws); also supports Webhook, reverse WS (via httpHostToken), and SSE (HTTP GET /event, parsing text/event-stream via fetch).

Features

• Milky protocol compatible (events + HTTP API)
• Convention-based defineAdapter / definePlugin (no usePlugin needed)
• Forward WebSocket (connection: ws): the application connects to the protocol endpoint ws(s)://baseUrl/event
• access_token authentication (Bearer + query)
• Inbound via messageGatewayToken; outbound send({ target, payload }) -> HTTP send_*_message

Installation

pnpm add @zhin.js/adapter-milky

Plugin Runtime

• @zhin.js/adapter — convention-based adapters/milky.ts (defineAdapter)
• @zhin.js/core — messageGatewayToken inbound/outbound
• @zhin.js/plugin-runtime — plugin.ts (definePlugin)
• Configuration goes to plugins.<instanceKey> via the plugin's schema.json

Inbound: gateway.receive({ adapter, target: "private:uid"|"group:gid", content, sender, metadata }) Outbound: send({ target, payload }) -> HTTP send_private_message / send_group_message (payload is rendered by gateway/core; no segment-mapper)

Minimal Configuration

# zhin.config.yml (Plugin Runtime)
plugins:
  milky:
    connection: ws
    reconnect_interval: 5000
    heartbeat_interval: 30000
    endpoints:
      - name: milky-bot
        baseUrl: "http://127.0.0.1:8080"
        access_token: "${MILKY_ACCESS_TOKEN}"

The root plugin zhin.plugins (or project graph) must reference @zhin.js/adapter-milky (instanceKey: milky).

Connection Modes

connection	Status
ws	Implemented (recommended)
sse	HTTP GET /event (Accept: text/event-stream)
wss	Implemented: reverse WS (httpHostToken)

Authentication

• Bearer: Authorization: Bearer <access_token>
• Forward WS attaches request headers during Upgrade and includes access_token in the URL query
• HTTP API uses the same Header / query authentication

Message ID

{message_scene}:{peer_id}:{message_seq} (e.g., group:123456:10001).

AI Tools

Category	Path
Permit vocabulary	agent/PERMITS.md
Skill documentation	agent/skills/milky.md

Documentation Links

• Milky Quick Start
• Milky Communication
• Adapters overview

License

MIT License