@jaxonchenjc/claude-wechat-channel 0.1.0 → 1.0.0

package/.claude-plugin/marketplace.json

@@ -14,7 +14,7 @@
         "repo": "jaxxjj/claude-wechat-channel"
       },
       "description": "WeChat channel for Claude Code — login with QR code, receive and reply to WeChat messages",
-      "version": "0.1.0",
+      "version": "1.0.0",
       "author": {
         "name": "jaxxjj"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wechat",
   "description": "WeChat channel for Claude Code \u2014 two-way messaging bridge via iLink Bot API. Login with QR code, receive and reply to WeChat messages from your Claude Code session.",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "keywords": [
     "wechat",
     "weixin",

package/README.md

@@ -1,6 +1,6 @@
 # WeChat Channel for Claude Code
 
-Two-way messaging bridge between WeChat and Claude Code via the iLink Bot API. Send a message from WeChat, Claude processes it and replies back — all while running against your local files.
+Two-way messaging bridge between WeChat and Claude Code via the iLink Bot API.
 
 **Background**: Tencent released [`@tencent-weixin/openclaw-weixin`](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — a WeChat channel for [OpenClaw](https://docs.openclaw.ai). This project brings the same capability to Claude Code, following the official [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram) and [Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord) channel plugin patterns.
 
@@ -9,67 +9,51 @@ Two-way messaging bridge between WeChat and Claude Code via the iLink Bot API. S
 - QR code login — scan with WeChat to connect
 - Text, image, voice, file, and video message support
 - Voice messages auto-transcribed (WeChat server-side STT)
-- Image/file/video download + AES-128-ECB decryption from CDN
+- Image/file/video CDN download with AES-128-ECB decryption
 - File/image/video sending via CDN upload
-- Typing indicator ("对方正在输入...")
-- Long message auto-chunking (4000 char limit)
+- Typing indicator
+- Long message auto-chunking
+- Poll cursor persistence (no message replay on restart)
 
 ## Prerequisites
 
-- [Claude Code](https://claude.com/claude-code) v2.1.80+, authenticated with claude.ai
+- [Claude Code](https://claude.com/claude-code) v2.1.80+
 - [Bun](https://bun.sh) runtime
 - A WeChat account
 
-## Install
-
-### Option A: Plugin marketplace (recommended)
-
-```bash
-# In Claude Code:
-/plugin marketplace add jaxxjj/claude-wechat-channel
-/plugin install wechat@claude-wechat-channel
-```
+## Quick Start
 
-### Option B: npm
+### 1. Install
 
 ```bash
-npx claude-wechat-channel install
+claude --dangerously-skip-permissions --dangerously-load-development-channels plugin:wechat@claude-wechat-channel
 ```
 
-This auto-configures the MCP server in `~/.claude.json`.
+Then inside Claude Code:
 
-### Option C: Manual (clone)
-
-```bash
-git clone https://github.com/jaxxjj/claude-wechat-channel.git
-cd claude-wechat-channel && bun install
-# Add MCP server to ~/.claude.json manually (see below)
 ```
-
-## Quick Start
-
-### 1. Start Claude Code with the channel
-
-```bash
-# If installed via marketplace:
-claude --dangerously-load-development-channels plugin:wechat@claude-wechat-channel
-
-# If installed via npm or manual:
-claude --dangerously-load-development-channels server:wechat
+/plugin marketplace add jaxxjj/claude-wechat-channel
+/plugin install wechat@claude-wechat-channel
+/reload-plugins
 ```
 
-### 2. Log in with QR code
+### 2. Login
 
-Inside Claude Code, run:
 ```
 /wechat:configure login
 ```
 
-Scan the QR code with WeChat on your phone. Credentials are saved to `~/.claude/channels/wechat/account.json`.
+Opens a QR code link — scan with WeChat. Credentials saved automatically.
+
+### 3. Restart
+
+Exit Claude Code, then:
 
-### 3. Restart and use
+```bash
+claude --dangerously-skip-permissions --dangerously-load-development-channels plugin:wechat@claude-wechat-channel
+```
 
-Exit Claude Code, run the same start command again. Now any WeChat contact who messages you will have their message appear in your Claude Code session. Claude processes it and replies through WeChat.
+Done. WeChat messages now arrive in your Claude Code session. Claude processes them and replies back through WeChat.
 
 ## How It Works
 
@@ -83,74 +67,66 @@ WeChat contact sends you a message
   → Reply appears in WeChat
 ```
 
-Access is gated by WeChat's QR code login — only contacts of the logged-in account can send messages. No separate pairing or allowlist needed (unlike Telegram/Discord bots which are publicly discoverable).
+Access is gated by WeChat's QR code login — only contacts of the logged-in account can send messages.
 
 ## Supported Message Types
 
 | Type | Inbound | Outbound |
 |------|---------|----------|
-| Text | Direct text extraction | Auto-chunked at 4000 chars |
-| Image | CDN download + AES decrypt → `image_path` in meta | CDN upload + encrypt |
-| Voice | Server-side speech-to-text (`voice_item.text`) | — |
-| File (PDF, etc) | CDN download + AES decrypt → `attachment_path` in meta | CDN upload + encrypt |
-| Video | CDN download + AES decrypt → `attachment_path` in meta | CDN upload + encrypt |
+| Text | Direct | Auto-chunked |
+| Image | CDN download + AES decrypt | CDN upload + encrypt |
+| Voice | Server-side speech-to-text | — |
+| File (PDF, etc) | CDN download + AES decrypt | CDN upload + encrypt |
+| Video | CDN download + AES decrypt | CDN upload + encrypt |
 
-## Tools Available to Claude
+## Alternative Install Methods
 
-| Tool | Description |
-|------|-------------|
-| `reply` | Send text + optional file attachments back to WeChat |
-| `send_typing` | Show "typing..." indicator in WeChat |
+### npm
 
-## Plugin Structure
+```bash
+npx @jaxonchenjc/claude-wechat-channel install
+claude --dangerously-skip-permissions --dangerously-load-development-channels server:wechat
+```
 
+### Manual clone
+
+```bash
+git clone https://github.com/jaxxjj/claude-wechat-channel.git
+cd claude-wechat-channel && bun install
 ```
-claude-wechat-channel/
-├── .claude-plugin/plugin.json   # Plugin manifest
-├── .mcp.json                    # MCP server config
-├── package.json                 # Dependencies
-├── server.ts                    # Channel server
-├── skills/
-│   └── configure/SKILL.md       # /wechat:configure (QR login)
-├── README.md
-└── LICENSE
+
+Add to `~/.claude.json` under `mcpServers`:
+
+```json
+{
+  "wechat": {
+    "command": "bun",
+    "args": ["run", "--cwd", "/path/to/claude-wechat-channel", "--shell=bun", "--silent", "start"],
+    "type": "stdio"
+  }
+}
 ```
 
 ## State Files
 
 ```
 ~/.claude/channels/wechat/
-├── account.json       # Login credentials (token + base URL), chmod 600
-└── inbox/             # Downloaded media files (images, files, videos)
+├── account.json   # Login credentials (chmod 600)
+├── poll_cursor    # Long-poll cursor (prevents replay on restart)
+└── inbox/         # Downloaded media files
 ```
 
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `WECHAT_STATE_DIR` | `~/.claude/channels/wechat` | Override state directory |
-
-## Differences from Telegram/Discord Plugins
-
-| Aspect | Telegram/Discord | WeChat |
-|--------|-----------------|--------|
-| Authentication | Paste bot token | Scan QR code with phone |
-| Access control | Pairing codes + allowlist | QR code login (contacts-only) |
-| Bot identity | Separate bot account | Your own WeChat account |
-| Message history | Telegram: none; Discord: fetch_messages | None |
-| Media handling | Telegram: direct URL; Discord: attachment download | CDN + AES-128-ECB encryption |
-
 ## Limitations
 
 - **Session expiry**: WeChat sessions may expire; re-run `/wechat:configure login`
 - **Single session**: Only one Claude Code session can poll at a time
-- **No message history**: Real-time only, no lookback
-- **Context tokens**: Stored in-memory; restart loses conversation context (next message restores it)
+- **No message history**: Real-time only
+- **Channels research preview**: Requires `--dangerously-load-development-channels` flag
 
 ## Credits
 
 - WeChat iLink Bot API by Tencent
-- Channel architecture inspired by [claude-plugins-official](https://github.com/anthropics/claude-plugins-official) (Telegram/Discord)
+- Channel architecture inspired by [claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
 - CDN encryption protocol referenced from [`@tencent-weixin/openclaw-weixin`](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaxonchenjc/claude-wechat-channel",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "WeChat channel plugin for Claude Code — two-way messaging bridge via iLink Bot API",
   "license": "MIT",
   "type": "module",
@@ -29,8 +29,7 @@
   "author": "jaxxjj",
   "homepage": "https://github.com/jaxxjj/claude-wechat-channel",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "qrcode-terminal": "^0.12.0"
+    "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.8",

package/server.ts

@@ -32,6 +32,7 @@ const STATE_DIR = process.env.WECHAT_STATE_DIR ?? join(homedir(), '.claude', 'ch
 const ENV_FILE = join(STATE_DIR, '.env')
 const ACCOUNT_FILE = join(STATE_DIR, 'account.json')
 const INBOX_DIR = join(STATE_DIR, 'inbox')
+const CURSOR_FILE = join(STATE_DIR, 'poll_cursor')
 
 // Load .env — plugin-spawned servers don't get an env block.
 try {
@@ -130,6 +131,7 @@ async function apiCall(baseUrl: string, endpoint: string, body: unknown, token:
 
 // ---------------------------------------------------------------------------
 // Context token management — WeChat requires echoing context_token in replies
+// In-memory cache as fallback; primary source is the tool parameter from Claude.
 // ---------------------------------------------------------------------------
 
 const contextTokens = new Map<string, string>()
@@ -142,6 +144,12 @@ function getContextToken(userId: string): string | undefined {
   return contextTokens.get(userId)
 }
 
+function resolveContextToken(explicit: string | undefined, userId: string): string {
+  const token = explicit || getContextToken(userId)
+  if (!token) throw new Error(`No context_token for ${userId} — the user must message first`)
+  return token
+}
+
 // ---------------------------------------------------------------------------
 // Typing indicator
 // ---------------------------------------------------------------------------
@@ -170,11 +178,8 @@ async function sendTyping(account: WechatAccount, userId: string, status: 1 | 2
 // Send message
 // ---------------------------------------------------------------------------
 
-async function sendMessage(account: WechatAccount, toUserId: string, text: string): Promise<{ messageId: string }> {
-  const contextToken = getContextToken(toUserId)
-  if (!contextToken) {
-    throw new Error(`No context_token for ${toUserId} — the user must message first`)
-  }
+async function sendMessage(account: WechatAccount, toUserId: string, text: string, explicitContextToken?: string): Promise<{ messageId: string }> {
+  const contextToken = resolveContextToken(explicitContextToken, toUserId)
 
   const clientId = `claude-wechat-${randomBytes(8).toString('hex')}`
   const res = await apiCall(account.baseUrl, 'ilink/bot/sendmessage', {
@@ -187,7 +192,7 @@ async function sendMessage(account: WechatAccount, toUserId: string, text: strin
       message_state: 2, // FINISH
       item_list: [{ type: 1, text_item: { text } }],
     },
-    base_info: { channel_version: '0.0.1' },
+    base_info: { channel_version: '1.0.0' },
   }, account.token) as Record<string, unknown>
 
   return { messageId: String(res.message_id ?? clientId) }
@@ -258,12 +263,9 @@ async function sendFileMessage(
   account: WechatAccount,
   toUserId: string,
   filePath: string,
-  caption?: string,
+  explicitContextToken?: string,
 ): Promise<{ messageId: string }> {
-  const contextToken = getContextToken(toUserId)
-  if (!contextToken) {
-    throw new Error(`No context_token for ${toUserId} — the user must message first`)
-  }
+  const contextToken = resolveContextToken(explicitContextToken, toUserId)
 
   const plaintext = readFileSync(filePath)
   const rawsize = plaintext.length
@@ -306,9 +308,7 @@ async function sendFileMessage(
     mediaItem = { type: 4, file_item: { media: cdnMedia, file_name: fileName, len: String(rawsize) } }
   }
 
-  const items: Record<string, unknown>[] = []
-  if (caption) items.push({ type: 1, text_item: { text: caption } })
-  items.push(mediaItem)
+  const items: Record<string, unknown>[] = [mediaItem]
 
   let lastMessageId = '0'
   for (const item of items) {
@@ -319,7 +319,7 @@ async function sendFileMessage(
         context_token: contextToken, message_type: 2, message_state: 2,
         item_list: [item],
       },
-      base_info: { channel_version: '0.0.1' },
+      base_info: { channel_version: '1.0.0' },
     }, account.token) as Record<string, unknown>
     lastMessageId = String(res.message_id ?? res.msg_id ?? '0')
   }
@@ -402,9 +402,9 @@ const mcp = new Server(
     instructions: [
       'The sender reads WeChat, not this session. Anything you want them to see must go through the reply tool — your transcript output never reaches their chat.',
       '',
-      'Messages from WeChat arrive as <channel source="wechat" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. If the tag has attachment_path, Read that file — it is a document (PDF, etc) or video the sender sent. Reply with the reply tool — pass chat_id back.',
+      'Messages from WeChat arrive as <channel source="wechat" chat_id="..." context_token="..." message_id="..." user="..." ts="...">. If the tag has image_path or attachment_path, use the Read tool directly on that file path — it handles images and PDFs natively, no external tools needed. Reply with the reply tool — pass chat_id and context_token back. The context_token is REQUIRED for delivery.',
       '',
-      'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Images send as photos; videos as video messages; other types as file attachments. Use send_typing before long operations to show "typing..." in WeChat.',
+      'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Images send as photos; videos as video messages; other types as file attachments.',
       '',
       'WeChat has no history or search API — you only see messages as they arrive. If you need earlier context, ask the user to paste it or summarize.',
     ].join('\n'),
@@ -416,30 +416,20 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: 'reply',
       description:
-        'Reply on WeChat. Pass chat_id from the inbound message. Optionally pass files (absolute paths) to attach images, videos, or documents.',
+        'Reply on WeChat. Pass chat_id and context_token from the inbound message. context_token is required for delivery.',
       inputSchema: {
         type: 'object',
         properties: {
           chat_id: { type: 'string', description: 'WeChat user ID from the inbound <channel> tag' },
           text: { type: 'string', description: 'Message text to send' },
+          context_token: { type: 'string', description: 'context_token from the inbound <channel> tag. Required for delivery.' },
           files: {
             type: 'array',
             items: { type: 'string' },
             description: 'Absolute file paths to attach. Images send as photos; videos as video messages; others as file attachments. Max 50MB each.',
           },
         },
-        required: ['chat_id', 'text'],
-      },
-    },
-    {
-      name: 'send_typing',
-      description: 'Show typing indicator in WeChat. Call before long operations.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          chat_id: { type: 'string', description: 'WeChat user ID' },
-        },
-        required: ['chat_id'],
+        required: ['chat_id', 'text', 'context_token'],
       },
     },
   ],
@@ -460,6 +450,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
       case 'reply': {
         const chat_id = args.chat_id as string
         const text = args.text as string
+        const ct = args.context_token as string | undefined
         const files = (args.files as string[] | undefined) ?? []
 
         for (const f of files) {
@@ -477,7 +468,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
 
         try {
           for (const c of chunks) {
-            const result = await sendMessage(account, chat_id, c)
+            const result = await sendMessage(account, chat_id, c, ct)
             sentIds.push(result.messageId)
           }
         } catch (err) {
@@ -486,7 +477,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
         }
 
         for (const f of files) {
-          const result = await sendFileMessage(account, chat_id, f)
+          const result = await sendFileMessage(account, chat_id, f, ct)
           sentIds.push(result.messageId)
         }
 
@@ -495,10 +486,6 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
           : `sent ${sentIds.length} parts (ids: ${sentIds.join(', ')})`
         return { content: [{ type: 'text', text: result }] }
       }
-      case 'send_typing': {
-        await sendTyping(account, args.chat_id as string, 1)
-        return { content: [{ type: 'text', text: 'typing indicator sent' }] }
-      }
       default:
         return {
           content: [{ type: 'text', text: `unknown tool: ${req.params.name}` }],
@@ -548,12 +535,17 @@ void (async () => {
 
   process.stderr.write(`wechat channel: starting message polling\n`)
 
-  let syncBuf = ''
+  // Load persisted poll cursor — prevents message replay on restart
+  let cursor = ''
+  try {
+    cursor = readFileSync(CURSOR_FILE, 'utf8').trim()
+    process.stderr.write(`wechat channel: resumed poll cursor (${cursor.length} bytes)\n`)
+  } catch {}
 
   for (let attempt = 1; !shuttingDown; ) {
     try {
       const res = await apiCall(account.baseUrl, 'ilink/bot/getupdates', {
-        get_updates_buf: syncBuf,
+        get_updates_buf: cursor,
       }, account.token, 40000) as Record<string, unknown>
 
       const errcode = res.errcode as number | undefined
@@ -568,7 +560,13 @@ void (async () => {
         continue
       }
 
-      if (res.get_updates_buf) syncBuf = res.get_updates_buf as string
+      if (res.get_updates_buf) {
+        cursor = res.get_updates_buf as string
+        try {
+          mkdirSync(STATE_DIR, { recursive: true })
+          writeFileSync(CURSOR_FILE, cursor)
+        } catch {}
+      }
 
       const msgs = (res.msgs ?? []) as WechatMessage[]
       attempt = 1
@@ -618,6 +616,7 @@ void (async () => {
           user_id: senderId,
           ts,
         }
+        if (msg.context_token) meta.context_token = msg.context_token
         if (msg.message_id != null) meta.message_id = String(msg.message_id)
         if (imagePath) meta.image_path = imagePath
         if (attachmentPath) meta.attachment_path = attachmentPath

package/skills/configure/SKILL.md

@@ -1,64 +1,83 @@
 ---
 name: configure
-description: Set up the WeChat channel — scan QR code to log in. Use when the user asks to configure WeChat, log in, check status, or reconnect.
+description: Set up the WeChat channel — scan QR code to log in. Use when the user asks to configure WeChat, login, check status, or reconnect.
 user-invocable: true
 allowed-tools:
   - Read
   - Write
-  - Bash(ls *)
-  - Bash(mkdir *)
-  - Bash(chmod *)
   - Bash(curl *)
+  - Bash(mkdir *)
 ---
 
 # /wechat:configure — WeChat Channel Setup
 
-Handles QR code login. WeChat access is gated by the QR code scan itself —
-only contacts of the logged-in account can send messages. No separate
-pairing or allowlist needed.
-
 Arguments passed: `$ARGUMENTS`
 
 ---
 
-## Dispatch on arguments
-
-### No args — status
-
-1. **Account** — check `~/.claude/channels/wechat/account.json`. Show
-   logged-in/not-logged-in. If logged in, show the base URL (masked).
-2. **What next**:
-   - Not logged in → *"Run `/wechat:configure login` to scan QR code."*
-   - Logged in → *"Ready. Messages from your WeChat contacts will reach
-     this session."*
-
-### `login` — QR code login
-
-1. `mkdir -p ~/.claude/channels/wechat`
-2. GET `https://ilinkai.weixin.qq.com/ilink/bot/get_bot_qrcode?bot_type=3`
-3. The response has `qrcode` (ID) and `qrcode_img_content` (URL).
-   Display the `qrcode_img_content` URL as a QR code in the terminal
-   using `npx qrcode-terminal "<url>"`, or show the URL directly.
-4. Tell the user: *"Scan this QR code with WeChat on your phone."*
-5. Poll status every 2-3 seconds until confirmed or timeout (5 minutes):
-   ```
-   GET https://ilinkai.weixin.qq.com/ilink/bot/get_qrcode_status?qrcode=<qrcode>
-   ```
-   Statuses: `wait`, `scaned`, `confirmed`, `expired`.
-6. On `confirmed`, save to `~/.claude/channels/wechat/account.json`:
-   ```json
-   {"token": "<bot_token>", "baseUrl": "<baseurl>"}
-   ```
-   `chmod 600` the file.
-7. Confirm: *"Logged in! Restart Claude Code to start receiving messages."*
-
-### `logout` — remove credentials
-
-Delete `~/.claude/channels/wechat/account.json`. Confirm.
+## No args — status
 
----
+1. Read `~/.claude/channels/wechat/account.json`. Show logged-in or not.
+2. If logged in: *"Ready. Restart Claude Code to start receiving messages."*
+3. If not: *"Run `/wechat:configure login` to connect."*
+
+## `login`
+
+### Step 1: Get QR code
+
+```bash
+curl -s 'https://ilinkai.weixin.qq.com/ilink/bot/get_bot_qrcode?bot_type=3'
+```
+
+Response: `{"qrcode":"<token>","qrcode_img_content":"<url>","ret":0}`
+
+Generate a QR image URL:
+`https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=<url-encoded qrcode_img_content>`
+
+Print ONLY the QR image URL. Tell the user: *"Open this link in a browser, then scan the QR code with WeChat."*
+
+Then immediately start polling (don't wait for user to say they scanned).
+
+IMPORTANT: In zsh, `status` is a read-only variable. Use `scan_status` or
+another name when parsing the response.
+
+```bash
+for i in $(seq 1 60); do
+  result=$(curl -s "https://ilinkai.weixin.qq.com/ilink/bot/get_qrcode_status?qrcode=<qrcode>")
+  scan_status=$(echo "$result" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
+  if [ "$scan_status" = "confirmed" ]; then echo "$result"; break; fi
+  if [ "$scan_status" = "expired" ]; then echo "expired"; break; fi
+  sleep 3
+done
+```
+
+Parse the result:
+- `"status":"confirmed"` — success! Extract `bot_token`, `baseurl`
+- `"status":"expired"` — tell user to run login again
+
+### Step 3: Save credentials
+
+```bash
+mkdir -p ~/.claude/channels/wechat
+```
+
+Write `~/.claude/channels/wechat/account.json`:
+```json
+{
+  "token": "<bot_token>",
+  "baseUrl": "<baseurl>"
+}
+```
+
+Then `chmod 600 ~/.claude/channels/wechat/account.json`.
+
+Tell user:
+```
+✅ Logged in! Restart Claude Code with:
+
+claude --dangerously-skip-permissions --dangerously-load-development-channels plugin:wechat@claude-wechat-channel
+```
 
-## Implementation notes
+## `logout`
 
-- The server reads `account.json` at boot. Login changes need a restart.
-- The QR code expires after a few minutes. If it times out, re-run login.
+Delete `~/.claude/channels/wechat/account.json`.