@spritesensei/wechat-cli 1.0.0

package/README.md

@@ -0,0 +1,145 @@
+# wechat-cli
+
+基于 `@wechatbot/wechatbot` SDK 的微信命令行工具，类似 lark-cli 风格。
+
+```bash
+npm install -g @spritesensei/wechat-cli
+wechat-cli --help
+```
+
+---
+
+## 安装
+
+```bash
+# 全局安装（推荐）
+npm install -g @spritesensei/wechat-cli
+
+# 或从源码
+git clone https://github.com/snowball-dev/wechat-cli.git
+cd wechat-cli
+npm install
+npm link
+```
+
+## AI Agent Skill
+
+wechat-cli 提供 AI Agent Skill，支持 Claude Code、Cursor、Windsurf、Gemini CLI 等 70+ AI 工具安装后通过 `/wechat-cli` 调出用法。
+
+skill 源文件在项目的 `skills/wechat-cli/SKILL.md`，可通过 npm 包分发安装。
+
+### 安装 Agent Skill
+
+```bash
+# 全局安装（推荐，本机所有对话可用）
+npx skills add @spritesensei/wechat-cli -g
+
+# 项目级安装（仅该项目目录下可用）
+npx skills add @spritesensei/wechat-cli
+```
+
+`skills` CLI 的两种模式：
+
+| 模式 | 安装位置 | 作用范围 |
+|------|---------|---------|
+| 默认（不加 `-g`） | `项目目录/.agents/skills/` | 仅该项目 |
+| `-g`（全局） | `~/.agents/skills/` | 本机所有会话 |
+
+安装后，在对话中输入 `/wechat-cli` 即可获取使用指南。
+
+## 使用
+
+### 登录（只需一次）
+
+```bash
+wechat-cli login
+# 生成二维码 PNG → 自动打开图片 → 手机微信扫码
+# 凭证自动保存到 ~/.wechat-cli/
+```
+
+加 `--force` 强制重新登录（已有凭证时）。
+
+### 发消息
+
+```bash
+# 文本
+wechat-cli send <用户ID> text "你好"
+
+# 图片
+wechat-cli send <用户ID> image ./照片.png
+
+# 视频
+wechat-cli send <用户ID> video ./视频.mp4
+
+# 文件（音频也当文件发）
+wechat-cli send <用户ID> file ./文档.pdf
+```
+
+可选的 `--caption "说明文字"` 参数。
+
+**注意：** 必须先收到过对方消息才能主动发（SDK 需要 context_token）。如果遇到 `NO_CONTEXT` 错误，先跑：
+
+```bash
+wechat-cli messages --count 1
+# 让对方发一条消息过来 → context 缓存 → 之后就能发了
+```
+
+### 拉取消息
+
+```bash
+wechat-cli messages --count 5
+# 启动长轮询，收集到 5 条消息后自动停止
+# --timeout 60 超时（秒），超时未收满也返回已收集的
+```
+
+默认输出 JSON，`--pretty` 美化。
+
+### 其他
+
+```bash
+wechat-cli status          # 查看登录状态
+wechat-cli logout          # 清除凭证
+wechat-cli --help          # 查看所有命令
+wechat-cli <命令> --help   # 查看子命令帮助
+```
+
+## 目录结构
+
+```
+wechat-cli/
+├── bin/wechat-cli.js       # 入口
+├── src/main.js              # Commander 配置
+├── src/core/bot.js          # createBot 工厂
+├── src/commands/
+│   ├── login.js             # 登录
+│   ├── send.js              # 发送（text/image/video/file）
+│   ├── messages.js          # 拉取消息
+│   ├── status.js            # 状态查询
+│   └── logout.js            # 登出
+├── src/utils/
+│   ├── output.js            # JSON 格式化输出
+│   └── qr.js                # 二维码生成
+├── skills/
+│   └── wechat-cli/
+│       └── SKILL.md         # AI Agent Skill
+├── package.json
+└── README.md
+```
+
+## 常见问题
+
+**Q: 发消息报 `NO_CONTEXT`？**
+A: 先 `wechat-cli messages --count 1`，让对方发条消息过来，刷新 context token。
+
+**Q: 凭证存在哪里？**
+A: `~/.wechat-cli/credentials.json`。SDK 默认是 `~/.wechatbot/`，可以复制过去复用。
+
+**Q: 语音消息？**
+A: iLink Bot API 不支持机器人发语音类型消息。音频当文件发：`send <uid> file ./audio.wav`。
+
+**Q: 报 `ret=-2` 错误？**
+A: 通常是会话过期或频率限制。重新 `login` 即可。
+
+## License
+
+MIT

package/bin/wechat-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../src/main.js';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@spritesensei/wechat-cli",
+  "version": "1.0.0",
+  "description": "WeChat CLI — send/receive WeChat messages via @wechatbot/wechatbot SDK",
+  "type": "module",
+  "bin": {
+    "wechat-cli": "bin/wechat-cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "wechat",
+    "weixin",
+    "cli",
+    "chatbot",
+    "ilink"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spritesensei/wechat-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/snowball-dev/wechat-cli/issues"
+  },
+  "homepage": "https://github.com/snowball-dev/wechat-cli#readme",
+  "license": "MIT",
+  "agents": {
+    "skills": {
+      "wechat-cli": {
+        "description": "WeChat CLI tool — send/receive messages via @wechatbot/wechatbot SDK",
+        "path": "./skills/wechat-cli/SKILL.md"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@wechatbot/wechatbot": "^2.1.1",
+    "commander": "^13.0.0",
+    "open": "^10.0.0",
+    "qrcode": "^1.5.0"
+  }
+}

package/skills/wechat-cli/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: wechat-cli
+description: Use when the user asks to send/receive WeChat messages, or when the project is wechat-cli — a CLI tool built on @wechatbot/wechatbot SDK for WeChat iLink Bot messaging
+---
+
+# wechat-cli
+
+基于 `@wechatbot/wechatbot` SDK 的微信命令行工具，类似 lark-cli 风格。
+
+## 安装
+
+```bash
+# 全局安装（推荐，安装后直接 wechat-cli 命令）
+npm install -g @spritesensei/wechat-cli
+
+# 或从源码
+git clone https://github.com/snowball-dev/wechat-cli.git
+cd wechat-cli
+npm install
+npm link
+```
+
+## 登录
+
+```bash
+wechat-cli login
+# 自动生成二维码图片并打开，手机微信扫码即可
+# 凭证自动保存到 ~/.wechat-cli/
+```
+
+加 `--force` 可强制重新登录。
+
+## 发消息
+
+必须先收到过对方消息（context token），否则会报 `NO_CONTEXT`。
+
+```bash
+# 先收一条消息刷新 context
+wechat-cli messages --count 1
+
+# 文本
+wechat-cli send <userId> text "内容"
+
+# 图片
+wechat-cli send <userId> image ./图片.png
+
+# 视频
+wechat-cli send <userId> video ./视频.mp4
+
+# 文件（音频也当文件发）
+wechat-cli send <userId> file ./文件.pdf --caption "说明"
+```
+
+## 拉取消息
+
+```bash
+wechat-cli messages --count 5 --timeout 30
+# 长轮询收集，到 count 或超时后自动停止，输出 JSON
+```
+
+## 其他命令
+
+```bash
+wechat-cli status     # 查看登录状态
+wechat-cli logout     # 清除凭证
+wechat-cli --help     # 所有命令
+wechat-cli <cmd> --help  # 子命令详情
+```
+
+## 注意事项
+
+- **context_token：** 需要先收消息才能主动发。`messages --count 1` 先让对方发一条过来
+- **会话过期：** `ret=-2` 错误通常表示会话过期或频率限制，重新 login
+- **语音：** iLink Bot API 不支持机器人发语音类型消息，音频请当文件发
+
+## 全局选项
+
+所有命令支持 `--pretty` 美化 JSON 输出。

package/src/commands/login.js

@@ -0,0 +1,56 @@
+import { createBot } from '../core/bot.js';
+import { renderQrCode } from '../utils/qr.js';
+import { outputJson, outputError } from '../utils/output.js';
+
+let qrShown = false;
+
+export function register(program) {
+  program
+    .command('login')
+    .description('Scan QR code to log in to WeChat')
+    .option('--force', 'Force re-login even if credentials exist')
+    .action(async (options, cmd) => {
+      try {
+        const loginCallbacks = {
+          onQrUrl: async (url) => {
+            if (qrShown) return;
+            qrShown = true;
+            try {
+              process.stderr.write('Opening QR code in image viewer...\n');
+              await renderQrCode(url);
+              process.stderr.write('Please scan the QR code with WeChat.\n');
+            } catch (err) {
+              process.stderr.write(`Failed to render QR code: ${err.message}\n`);
+            }
+          },
+          onScanned: () => {
+            process.stderr.write('QR code scanned! Confirm on your phone...\n');
+          },
+          onExpired: () => {
+            process.stderr.write('QR code expired, refreshing...\n');
+            qrShown = false;
+          },
+        };
+
+        const bot = await createBot({
+          loginCallbacks,
+          force: !!options.force,
+        });
+        const creds = bot.getCredentials();
+        await bot.stop();
+
+        if (!creds) {
+          outputError('Login failed — no credentials returned', 'LOGIN_FAILED');
+          return;
+        }
+
+        outputJson({
+          success: true,
+          userId: creds.userId,
+          accountId: creds.accountId,
+        }, { pretty: cmd.optsWithGlobals().pretty });
+      } catch (err) {
+        outputError(err.message, 'LOGIN_FAILED');
+      }
+    });
+}

package/src/commands/logout.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { outputJson } from '../utils/output.js';
+import { DEFAULT_STORAGE_DIR } from '../core/bot.js';
+
+export function register(program) {
+  program
+    .command('logout')
+    .description('Clear stored credentials and log out')
+    .action(async (options, cmd) => {
+      let removed = 0;
+
+      if (fs.existsSync(DEFAULT_STORAGE_DIR)) {
+        for (const file of fs.readdirSync(DEFAULT_STORAGE_DIR)) {
+          fs.rmSync(path.join(DEFAULT_STORAGE_DIR, file), { force: true, recursive: true });
+          removed++;
+        }
+      }
+
+      outputJson({
+        success: true,
+        removedFiles: removed,
+        storageDir: DEFAULT_STORAGE_DIR,
+      }, { pretty: cmd.optsWithGlobals().pretty });
+    });
+}

package/src/commands/messages.js

@@ -0,0 +1,69 @@
+import { createBot } from '../core/bot.js';
+import { outputJson, outputError } from '../utils/output.js';
+
+export function register(program) {
+  program
+    .command('messages')
+    .description('Pull recent messages (listens for N new messages, then stops)')
+    .option('-c, --count <number>', 'Number of messages to collect', '5')
+    .option('-t, --timeout <seconds>', 'Max wait time in seconds', '60')
+    .action(async (options, cmd) => {
+      const count = parseInt(options.count, 10);
+      const timeoutMs = parseInt(options.timeout, 10) * 1000;
+
+      if (isNaN(count) || count < 1) {
+        outputError('--count must be a positive integer', 'INVALID_COUNT');
+        return;
+      }
+      if (isNaN(timeoutMs) || timeoutMs < 0) {
+        outputError('--timeout must be a non-negative integer', 'INVALID_TIMEOUT');
+        return;
+      }
+
+      try {
+        const bot = await createBot({});
+        const messages = [];
+        let finished = false;
+
+        bot.onMessage((msg) => {
+          messages.push({
+            userId: msg.userId,
+            text: msg.text,
+            type: msg.type,
+            timestamp: msg.timestamp,
+            images: msg.images?.map(i => ({ url: i.url, width: i.width, height: i.height })) ?? [],
+            files: msg.files?.map(f => ({ fileName: f.fileName, size: f.size, md5: f.md5 })) ?? [],
+            videos: msg.videos?.map(v => ({ durationMs: v.durationMs, width: v.width, height: v.height })) ?? [],
+            voices: msg.voices?.map(v => ({ durationMs: v.durationMs, text: v.text })) ?? [],
+          });
+
+          if (!finished && messages.length >= count) {
+            stopAndOutput();
+          }
+        });
+
+        const timer = setTimeout(() => {
+          stopAndOutput();
+        }, timeoutMs);
+
+        function stopAndOutput() {
+          if (finished) return;
+          finished = true;
+          clearTimeout(timer);
+          try { bot.stop(); } catch {}
+          outputJson({
+            messages,
+            total: messages.length,
+            requested: count,
+            timedOut: messages.length < count,
+          }, { pretty: cmd.optsWithGlobals().pretty });
+        }
+
+        await bot.start();
+        // bot.start() resolves when bot.stop() is called
+
+      } catch (err) {
+        outputError(err.message, 'MESSAGES_FAILED');
+      }
+    });
+}

package/src/commands/send.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createBot } from '../core/bot.js';
+import { outputJson, outputError } from '../utils/output.js';
+
+export function register(program) {
+  program
+    .command('send')
+    .description('Send a message to a user')
+    .argument('<userId>', 'Target user ID (e.g. xxx@im.wechat)')
+    .argument('<type>', 'Message type: text | image | video | file')
+    .argument('<content>', 'Text content (for text type) or file path (for image/video/file)')
+    .option('-c, --caption <text>', 'Caption for image/video/file')
+    .action(async (userId, type, content, options, cmd) => {
+      try {
+        const validTypes = ['text', 'image', 'video', 'file'];
+        if (!validTypes.includes(type)) {
+          outputError(`Invalid type "${type}". Must be one of: ${validTypes.join(', ')}`, 'INVALID_TYPE');
+          return;
+        }
+
+        const bot = await createBot({});
+        await bot.contextStore.load();
+
+        if (type === 'text') {
+          await bot.send(userId, { text: content });
+          await bot.stop();
+          outputJson({ success: true, userId, type }, { pretty: cmd.optsWithGlobals().pretty });
+          return;
+        }
+
+        // For media types: read file
+        const filePath = path.resolve(content);
+        if (!fs.existsSync(filePath)) {
+          outputError(`File not found: ${filePath}`, 'FILE_NOT_FOUND');
+          return;
+        }
+        const data = fs.readFileSync(filePath);
+        const fileName = path.basename(filePath);
+
+        if (type === 'image') {
+          await bot.send(userId, { image: data, caption: options.caption });
+        } else if (type === 'video') {
+          await bot.send(userId, { video: data, caption: options.caption });
+        } else {
+          await bot.send(userId, { file: data, fileName, caption: options.caption });
+        }
+
+        await bot.stop();
+
+        outputJson({
+          success: true,
+          userId,
+          type,
+        }, { pretty: cmd.optsWithGlobals().pretty });
+
+      } catch (err) {
+        if (err.name === 'NoContextError' || err.code === 'NO_CONTEXT') {
+          outputError(
+            `No context token for user "${userId}". First receive a message from them via "wechat-cli messages"`,
+            'NO_CONTEXT', 2);
+        } else {
+          outputError(err.message, 'SEND_FAILED');
+        }
+      }
+    });
+}

package/src/commands/status.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { outputJson } from '../utils/output.js';
+import { DEFAULT_STORAGE_DIR } from '../core/bot.js';
+
+export function register(program) {
+  program
+    .command('status')
+    .description('Show login status')
+    .action(async (options, cmd) => {
+      const credentialsPath = path.join(DEFAULT_STORAGE_DIR, 'credentials.json');
+      const credsExist = fs.existsSync(credentialsPath);
+
+      let credentials = null;
+      let contextCount = 0;
+
+      if (credsExist) {
+        try {
+          const raw = fs.readFileSync(credentialsPath, 'utf-8');
+          credentials = JSON.parse(raw);
+          // Count cached context tokens
+          const tokensPath = path.join(DEFAULT_STORAGE_DIR, 'context_tokens.json');
+          if (fs.existsSync(tokensPath)) {
+            const tokens = JSON.parse(fs.readFileSync(tokensPath, 'utf-8'));
+            contextCount = Object.keys(tokens).length;
+          }
+        } catch {}
+      }
+
+      outputJson({
+        loggedIn: !!credentials,
+        userId: credentials?.userId ?? null,
+        accountId: credentials?.accountId ?? null,
+        savedAt: credentials?.savedAt ?? null,
+        storageDir: DEFAULT_STORAGE_DIR,
+        cachedUsers: contextCount,
+      }, { pretty: cmd.optsWithGlobals().pretty });
+    });
+}

package/src/core/bot.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import os from 'node:os';
+import { WeChatBot } from '@wechatbot/wechatbot';
+
+export const DEFAULT_STORAGE_DIR = path.join(os.homedir(), '.wechat-cli');
+
+/**
+ * Create a WeChatBot instance, auto-load stored credentials.
+ * Returns the bot ready to use (logged in, not yet started).
+ * Does NOT call bot.start() — caller decides whether to poll.
+ *
+ * @param {object} [options]
+ * @param {string} [options.storageDir] - Storage directory (default: ~/.wechat-cli)
+ * @param {object} [options.loginCallbacks] - QR login callbacks
+ * @param {boolean} [options.force] - Force re-login even if credentials exist
+ */
+export async function createBot({ storageDir = DEFAULT_STORAGE_DIR, loginCallbacks = {}, force } = {}) {
+  const bot = new WeChatBot({
+    storage: 'file',
+    storageDir,
+    logLevel: 'warn',
+    loginCallbacks,
+  });
+
+  await bot.login({ force, callbacks: loginCallbacks });
+  return bot;
+}

package/src/main.js

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+import { register as registerLogin } from './commands/login.js';
+import { register as registerSend } from './commands/send.js';
+import { register as registerMessages } from './commands/messages.js';
+import { register as registerStatus } from './commands/status.js';
+import { register as registerLogout } from './commands/logout.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('wechat-cli')
+  .description('WeChat CLI — send/receive messages via @wechatbot/wechatbot')
+  .version(pkg.version)
+  .option('--pretty', 'Pretty-print JSON output');
+
+// Register all commands
+registerLogin(program);
+registerSend(program);
+registerMessages(program);
+registerStatus(program);
+registerLogout(program);
+
+program.parse(process.argv);

package/src/utils/output.js

@@ -0,0 +1,23 @@
+/**
+ * Write JSON result to stdout.
+ * @param {*} data - data to serialize
+ * @param {{ pretty?: boolean }} options
+ */
+export function outputJson(data, options = {}) {
+  const space = options.pretty ? 2 : undefined;
+  const text = JSON.stringify(data, null, space) + '\n';
+  process.stdout.write(text);
+}
+
+/**
+ * Write error JSON to stderr and exit.
+ * @param {string} message
+ * @param {string} [code]
+ * @param {number} [exitCode]
+ */
+export function outputError(message, code = 'UNKNOWN_ERROR', exitCode = 1) {
+  const error = { error: true, code, message };
+  const text = JSON.stringify(error) + '\n';
+  process.stderr.write(text);
+  process.exit(exitCode);
+}

package/src/utils/qr.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import QRCode from 'qrcode';
+import open from 'open';
+
+/**
+ * Generate a QR code PNG from a URL, save to temp dir, and open it.
+ * Falls back to printing the URL if the image viewer cannot be launched.
+ * @param {string} url - the QR URL to encode
+ * @returns {Promise<{ filePath: string }>}
+ */
+export async function renderQrCode(url) {
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'wechat-cli-qr-'));
+  const filePath = path.join(tmpDir, 'wechat-login.png');
+
+  await QRCode.toFile(filePath, url, {
+    type: 'png',
+    width: 400,
+    margin: 2,
+    color: { dark: '#000000', light: '#ffffff' },
+  });
+
+  try {
+    await open(filePath);
+  } catch {
+    // Fallback: print the QR URL if open fails (e.g. headless/CI)
+    process.stderr.write(`QR code image saved to: ${filePath}\n`);
+    process.stderr.write(`QR code URL: ${url}\n`);
+    process.stderr.write('Please open this URL in a browser to scan with WeChat.\n');
+  }
+
+  return { filePath };
+}