@kyan-du/agent-wechat-wechaty-puppet

@kyan-du/agent-wechat-wechaty-puppet

Wechaty Puppet for agent-wechat. Bridges any Wechaty bot to WeChat via the agent-wechat REST/WebSocket server.

Release boundary: Fork npm, GHCR, and hosted documentation are unavailable until P1-B publishes and verifies them. Clone this repository, run corepack enable && pnpm install --frozen-lockfile && pnpm build && pnpm build:image, and start the local image with pnpm cli start.

Documentation

Prerequisites

• An agent-wechat server running — set up via the CLI or from the agent-wechat repo:

  pnpm cli start     # from a built repository checkout

  Login is not required as a separate CLI step; you can log in through the puppet QR flow.
• Node.js >= 22

Install

# Pending P1-B (not available yet): npm install @kyan-du/agent-wechat-wechaty-puppet wechaty wechaty-puppet
git clone https://github.com/kyan-du/agent-wechat.git
cd agent-wechat
corepack enable && pnpm install --frozen-lockfile
pnpm build
PUPPET_TARBALL=$(cd packages/wechaty-puppet && npm pack --silent)
mkdir -p /tmp/agent-wechat-wechaty-consumer
cd /tmp/agent-wechat-wechaty-consumer
npm init -y
npm install "$OLDPWD/packages/wechaty-puppet/$PUPPET_TARBALL" wechaty wechaty-puppet

Create the example below as bot.mjs in that clean consumer directory and run node bot.mjs. This verifies the package import through its real tarball rather than workspace resolution.

Usage

import { WechatyBuilder } from 'wechaty'
import PuppetAgentWeChat from '@kyan-du/agent-wechat-wechaty-puppet'

const bot = WechatyBuilder.build({
  puppet: new PuppetAgentWeChat({
    serverUrl: 'http://localhost:6174',  // optional, this is the default
    token: 'your-token',                 // optional, reads from ~/.config/agent-wechat/token
  })
})

bot.on('scan', (qrcode, status) => {
  console.log(`Scan QR Code to login: ${status}\nhttps://wechaty.js.org/qrcode/${encodeURIComponent(qrcode)}`)
})

bot.on('login', user => console.log(`Logged in: ${user}`))

bot.on('message', async msg => {
  if (msg.text() === 'ding') {
    await msg.say('dong')
  }
})

await bot.start()

Configuration

Supported Features

How It Works

The puppet connects to the agent-wechat REST API (Rust server running inside a Docker container alongside WeChat desktop). It does not interact with WeChat directly.

• Login: WebSocket subscription to /api/ws/login drives QR scan events
• Messages: Polls GET /api/chats for unreads, then GET /api/messages/{chatId} for new messages
• Sending: POST /api/messages/send with text, image, or file payloads
• Media: GET /api/messages/{chatId}/media/{localId} for image/voice/video downloads
• Contacts: Full address book via GET /api/contacts
• Rooms: Derived from GET /api/chats (group chats)