pi-wechat-assistant

---

What is this?

pi-wechat-assistant is a pi extension that connects one WeChat user to one pi TUI session. It is not a generic chatbot bridge or a multi-session orchestrator — it is a personal assistant that lets you continue your pi conversation from WeChat when you step away from your computer.

Messages you send on WeChat are injected into the active pi session; AI replies are sent back to WeChat. Messages you type in TUI are also previewed on WeChat, keeping both sides in sync.

One WeChat user ↔ One pi TUI session. That's the whole scope.

Features

• 📱 Personal assistant — designed for a single user continuing a single pi session from WeChat
• 🔐 QR code login — scan with WeChat to authorize
• 🔄 Two-way sync — WeChat ↔ TUI messages are visible on both sides
• 🖼️ Image support — download, decrypt, and send images to the model for analysis
• 📁 File support — receive files from WeChat, save to project directory; send project files back
• 🗣️ Voice support — uses WeChat's built-in speech-to-text
• 💬 Message queuing & batching — consecutive messages are merged; multiple images wait for a text supplement
• 🔒 Exclusive lock — only one TUI session can hold the WeChat connection at a time
• 📊 Status bar — shows WeChat connection status and pending message count in TUI

Quick Start

Install

pi install npm:pi-wechat-assistant

Or from GitHub:

pi install git:github.com/shenjiecode/pi-wechat-assistant

Usage

In the pi TUI:

/wechat login
/wechat start

Then open WeChat, find the bot, and start messaging.

TUI Commands

All commands use /wechat with a subcommand:

Command	Description
/wechat login	Scan QR code to log in
/wechat login --force	Force re-scan
/wechat start	Start the WeChat connection
/wechat stop	Stop and release the lock
/wechat status	Show connection status and config
/wechat config	View image-related settings
/wechat config image-wait <ms>	Set batch wait time (default 8000)
/wechat config image-max <MB>	Set per-image size limit (default 50)
/wechat autostart	Toggle auto-start on session begin
/wechat logout	Clear credentials and stop

WeChat Remote Commands

Send text, voice, or images on WeChat to chat normally. Additional commands:

Command	Description
/status	Model, context usage, queue, config
/stop	Abort current generation
/model	List available models
/model <name>	Switch model
/config	View image config
/name <name>	Set session name
/session	Show session details
/help	Show help

Advanced: /thinking, /tools, /compact.

Supported Message Types

Type	Status
Text	✅
Voice	✅ (WeChat speech-to-text)
Image	✅ (downloaded and sent to model)
Quote reply	✅ (quoted text prepended)
File	✅ (saved to project directory)
Video	❌ Not supported

Configuration

Environment Variables

Variable	Description	Default
PI_WECHAT_DEBUG	Set to 1 to enable debug logging	Off
PI_WECHAT_DEBUG_FILE	Debug log file path	~/.pi/agent/wechat-assistant/debug.log
PI_WECHAT_IMAGE_BATCH_WAIT_MS	Batch wait time for images	8000
PI_WECHAT_IMAGE_MAX_BYTES	Per-image size limit	52428800 (50 MB)

Config Files

~/.pi/agent/wechat-assistant/
├── credentials.json   # Login credentials (mode 600)
├── config.json        # Auto-start, image limits
└── session.lock       # Exclusive lock file

config.json example:

{
  "autoStart": true,
  "imageBatchWaitMs": 8000,
  "imageMaxBytes": 52428800
}

Architecture

WeChat  ⇄  pi TUI session  ⇄  AI model + tools

• WeChat messages are fetched via iLink Bot API long polling
• Incoming messages are injected into the active pi session via pi.sendUserMessage()
• When you type in TUI, a preview is sent to WeChat
• AI replies are delivered incrementally (per message_end) and finalized on agent_end
• Only the TUI session that runs /wechat start holds the connection

FAQ

WeChat not responding? Run /wechat status to check. If the session expired, run /wechat login --force.

"Already occupied by another pi instance"? Another TUI session holds the lock. Run /wechat stop in that session.

Why aren't images processed immediately? Images wait up to 8 seconds for batching — so you can send multiple images and add a text description. The first image gets an acknowledgment immediately; if you send text during the wait, processing starts right away.

Development

git clone https://github.com/shenjiecode/pi-wechat-assistant.git
cd pi-wechat-assistant
npm install
npm run typecheck

# Quick test
pi -e ./src/index.ts

Releasing

npm version patch   # updates package.json, commits, and tags
git push --follow-tags   # triggers CI → npm publish + GitHub Release

License

MIT

---

---

这是什么？

pi-wechat-assistant 是一个 pi 扩展，将一个微信用户连接到一个 pi TUI 会话。它不是一个通用聊天机器人桥接，也不是多会话编排器——它是一个个人助手，让你离开电脑后可以通过微信继续和同一个 pi 会话交互。

你在微信里发的消息会被注入当前 pi 会话，AI 的回复会发回微信。你在 TUI 里输入的消息也会在微信端显示预览，保持两边同步。

一个微信用户 ↔ 一个 pi TUI 会话。 这就是全部的定位。

特性

• 📱 个人助手 — 为单用户远程操控单个 pi 会话设计
• 🔐 扫码登录 — 微信扫码授权
• 🔄 双向同步 — 微信 ↔ TUI 消息在两边都可见
• 🖼️ 图片支持 — 下载、解密、发送给模型分析
• 📁 文件支持 — 从微信接收文件保存到项目目录；发送项目文件回微信
• 🗣️ 语音支持 — 使用微信内置语音转文字
• 💬 消息排队与合并 — 连续消息自动合并；多张图片等待文字补充后一起处理
• 🔒 排他锁 — 同一时间只有一个 TUI 会话持有微信连接
• 📊 状态栏 — TUI 底部显示微信连接状态和待处理消息数

快速开始

安装

pi install npm:pi-wechat-assistant

或从 GitHub 安装：

pi install git:github.com/shenjiecode/pi-wechat-assistant

使用

在 pi TUI 中执行：

/wechat login
/wechat start

然后打开微信找到机器人，直接发消息即可。

TUI 命令

命令	说明
/wechat login	扫码登录
/wechat login --force	强制重新扫码
/wechat start	启动微信连接
/wechat stop	停止并释放锁
/wechat status	查看连接状态和配置
/wechat config	查看图片相关设置
/wechat config image-wait <ms>	设置图片批量等待时间，默认 8000
/wechat config image-max <MB>	设置单张图片大小上限，默认 50
/wechat autostart	开关自动启动
/wechat logout	清除凭证并停止

微信远程命令

微信里直接发文字/语音/图片就是正常对话。额外命令：

命令	说明
/status	查看模型、上下文、队列、配置
/stop	停止当前生成
/model	查看可用模型
/model <名称>	切换模型
/config	查看图片配置
/name <名称>	设置会话名称
/session	查看会话详情
/help	显示帮助

高级命令：/thinking、/tools、/compact。

支持的消息类型

类型	状态
文字	✅
语音	✅（微信语音转文字）
图片	✅（下载后发送给模型分析）
引用回复	✅（拼接引用文本）
文件	✅（保存到项目目录）
视频	❌ 暂不支持

配置

环境变量

变量	说明	默认值
PI_WECHAT_DEBUG	设为 1 开启调试日志	关闭
PI_WECHAT_DEBUG_FILE	调试日志路径	~/.pi/agent/wechat-assistant/debug.log
PI_WECHAT_IMAGE_BATCH_WAIT_MS	图片批量等待时间	8000
PI_WECHAT_IMAGE_MAX_BYTES	单张图片大小上限	52428800（50 MB）

配置文件

~/.pi/agent/wechat-assistant/
├── credentials.json   # 登录凭证（权限 600）
├── config.json        # 自动启动、图片限制
└── session.lock       # 排他锁文件

架构

微信  ⇄  pi TUI 会话  ⇄  AI 模型 + 工具

• 微信消息通过 iLink Bot API 长轮询获取
• 收到的消息通过 pi.sendUserMessage() 注入当前 pi 会话
• TUI 输入时微信端会收到预览
• AI 回复增量发送（每条 message_end 即发），agent_end 时补发遗漏
• 只有执行 /wechat start 的 TUI 会话持有连接

常见问题

微信没有回复？ 执行 /wechat status 检查状态。Session 过期则执行 /wechat login --force。

提示"已被其他 pi 实例占用"？ 另一个 TUI 会话持有锁，在那个会话执行 /wechat stop。

图片为什么不马上处理？ 图片默认等待 8 秒用于批量合并，方便你连发多张图再补描述。收到第一张图会立即回执，期间发文字则立即开始处理。

开发

git clone https://github.com/shenjiecode/pi-wechat-assistant.git
cd pi-wechat-assistant
npm install
npm run typecheck

# 快速测试
pi -e ./src/index.ts

发版

npm version patch   # 更新 package.json、提交、打 tag
git push --follow-tags   # 触发 CI → npm 发布 + GitHub Release

许可证

MIT

---

---

これは何？

pi-wechat-assistant は pi の拡張機能で、1人のWeChatユーザーを1つのpi TUIセッションに接続します。汎用チャットボットブリジでも、マルチセッションオーケストレーターでもありません。パソコンから離れている間、WeChatから同じpiセッションの会話を続けるためのパーソナルアシスタントです。

WeChatで送信したメッセージは現在のpiセッションに注入され、AIの返信がWeChatに送り返されます。TUIで入力したメッセージもWeChat側にプレビューが表示され、両側を同期します。

1人のWeChatユーザー ↔ 1つのpi TUIセッション。 それがこのプロジェクトのスコープです。

特徴

• 📱 パーソナルアシスタント — 単一ユーザーが単一のpiセッションをWeChatからリモート操作するために設計
• 🔐 QRコードログイン — WeChatでスキャンして認証
• 🔄 双方向同期 — WeChat ↔ TUIのメッセージが両側で閲覧可能
• 🖼️ 画像対応 — ダウンロード、復号、モデルに送信して分析
• 📁 ファイル対応 — WeChatからファイルを受信してプロジェクトディレクトリに保存、プロジェクトファイルをWeChatに送信
• 🗣️ 音声対応 — WeChat内蔵の音声認識を利用
• 💬 メッセージキューイング＆バッチ処理 — 連続メッセージの自動マージ、複数画像はテキスト補完を待ってから一括処理
• 🔒 排他ロック — 同時に1つのTUIセッションのみWeChat接続を保持
• 📊 ステータスバー — TUI下部にWeChat接続状態と保留メッセージ数を表示

クイックスタート

インストール

pi install npm:pi-wechat-assistant

またはGitHubから：

pi install git:github.com/shenjiecode/pi-wechat-assistant

使い方

pi TUIで以下を実行：

/wechat login
/wechat start

WeChatでボットを見つけて、メッセージを送るだけです。

TUIコマンド

コマンド	説明
/wechat login	QRコードをスキャンしてログイン
/wechat login --force	強制的に再スキャン
/wechat start	WeChat接続を開始
/wechat stop	停止してロックを解放
/wechat status	接続状態と設定を表示
/wechat config	画像関連設定を表示
/wechat config image-wait <ms>	バッチ待機時間を設定（デフォルト 8000）
/wechat config image-max <MB>	画像サイズ上限を設定（デフォルト 50）
/wechat autostart	セッション開始時の自動起動を切替
/wechat logout	認証情報をクリアして停止

WeChatリモートコマンド

WeChatでテキスト、音声、画像を送るだけで通常の会話になります。追加コマンド：

コマンド	説明
/status	モデル、コンテキスト使用量、キュー、設定
/stop	現在の生成を中止
/model	利用可能なモデル一覧
/model <名前>	モデル切替
/config	画像設定を表示
/name <名前>	セッション名を設定
/session	セッション詳細を表示
/help	ヘルプを表示

上級者向け：/thinking、/tools、/compact。

対応メッセージタイプ

タイプ	状態
テキスト	✅
音声	✅（WeChat音声認識）
画像	✅（ダウンロード後モデルに送信）
引用返信	✅（引用テキストを付加）
ファイル	✅（プロジェクトディレクトリに保存）
動画	❌ 未対応

設定

環境変数

変数	説明	デフォルト
PI_WECHAT_DEBUG	1 でデバッグログ有効	オフ
PI_WECHAT_DEBUG_FILE	デバッグログパス	~/.pi/agent/wechat-assistant/debug.log
PI_WECHAT_IMAGE_BATCH_WAIT_MS	画像バッチ待機時間	8000
PI_WECHAT_IMAGE_MAX_BYTES	画像サイズ上限	52428800（50 MB）

設定ファイル

~/.pi/agent/wechat-assistant/
├── credentials.json   # ログイン認証情報（権限 600）
├── config.json        # 自動起動、画像制限
└── session.lock       # 排他ロックファイル

アーキテクチャ

WeChat  ⇄  pi TUIセッション  ⇄  AIモデル + ツール

• WeChatメッセージはiLink Bot APIのロングポーリングで取得
• 受信メッセージは pi.sendUserMessage() で現在のpiセッションに注入
• TUIで入力するとWeChat側にプレビューが送信
• AI返信は増分的に送信（message_end ごと）、agent_end で残りを補完
• /wechat start を実行したTUIセッションのみが接続を保持

FAQ

WeChatから返信がない？ /wechat status で状態を確認。セッション期限切れなら /wechat login --force を実行。

「他のpiインスタンスが使用中」と表示？ 別のTUIセッションがロックを保持中。そのセッションで /wechat stop を実行。

画像がすぐに処理されない？ バッチ処理のため最大8秒待機。複数画像を連続送信後、テキストで補足できます。最初の画像は即座に確認応答、待機中にテキストを送ると即時処理。

開発

git clone https://github.com/shenjiecode/pi-wechat-assistant.git
cd pi-wechat-assistant
npm install
npm run typecheck

# クイックテスト
pi -e ./src/index.ts

リリース

npm version patch   # package.jsonを更新、コミット、タグ作成
git push --follow-tags   # CI → npm公開 + GitHub Release をトリガー

ライセンス

MIT

---

---

이것은 무엇인가요?

pi-wechat-assistant는 pi 확장 기능으로, 1명의 WeChat 사용자를 1개의 pi TUI 세션에 연결합니다. 범용 챗봇 브릿지도, 멀티 세션 오케스트레이터도 아닙니다. 컴퓨터를 떠나 있는 동안 WeChat에서 동일한 pi 세션 대화를 이어갈 수 있게 해주는 개인 어시스턴트입니다.

WeChat에서 보낸 메시지는 현재 pi 세션에 주입되고, AI 응답이 WeChat으로 돌아옵니다. TUI에서 입력한 메시지도 WeChat 측에 미리보기가 표시되어 양쪽을 동기화합니다.

1명의 WeChat 사용자 ↔ 1개의 pi TUI 세션. 그것이 이 프로젝트의 전체 범위입니다.

특징

• 📱 개인 어시스턴트 — 단일 사용자가 WeChat에서 단일 pi 세션을 원격 조작하도록 설계
• 🔐 QR 코드 로그인 — WeChat으로 스캔하여 인증
• 🔄 양방향 동기화 — WeChat ↔ TUI 메시지가 양쪽에서 표시
• 🖼️ 이미지 지원 — 다운로드, 복호화, 모델에 전송하여 분석
• 📁 파일 지원 — WeChat에서 파일을 수신하여 프로젝트 디렉토리에 저장, 프로젝트 파일을 WeChat으로 전송
• 🗣️ 음성 지원 — WeChat 내장 음성 인식 활용
• 💬 메시지 큐잉 & 배치 — 연속 메시지 자동 병합, 여러 이미지는 텍스트 보충을 대기 후 일괄 처리
• 🔒 배타적 잠금 — 동시에 하나의 TUI 세션만 WeChat 연결 유지
• 📊 상태 표시줄 — TUI 하단에 WeChat 연결 상태와 대기 메시지 수 표시

빠른 시작

설치

pi install npm:pi-wechat-assistant

또는 GitHub에서:

pi install git:github.com/shenjiecode/pi-wechat-assistant

사용법

pi TUI에서 실행:

/wechat login
/wechat start

WeChat에서 봇을 찾아 메시지를 보내기만 하면 됩니다.

TUI 명령어

명령어	설명
/wechat login	QR 코드 스캔하여 로그인
/wechat login --force	강제 재스캔
/wechat start	WeChat 연결 시작
/wechat stop	중지 및 잠금 해제
/wechat status	연결 상태 및 설정 표시
/wechat config	이미지 관련 설정 표시
/wechat config image-wait <ms>	배치 대기 시간 설정 (기본값 8000)
/wechat config image-max <MB>	이미지 크기 제한 설정 (기본값 50)
/wechat autostart	세션 시작 시 자동 시작 전환
/wechat logout	자격 증명 지우기 및 중지

WeChat 원격 명령어

WeChat에서 텍스트, 음성, 이미지를 보내면 일반 대화입니다. 추가 명령어:

명령어	설명
/status	모델, 컨텍스트 사용량, 큐, 설정
/stop	현재 생성 중단
/model	사용 가능한 모델 목록
/model <이름>	모델 전환
/config	이미지 설정 표시
/name <이름>	세션 이름 설정
/session	세션 상세 정보
/help	도움말 표시

고급: /thinking, /tools, /compact.

지원 메시지 유형

유형	상태
텍스트	✅
음성	✅ (WeChat 음성 인식)
이미지	✅ (다운로드 후 모델에 전송)
인용 답장	✅ (인용 텍스트 추가)
파일	✅ (프로젝트 디렉토리에 저장)
동영상	❌ 미지원

설정

환경 변수

변수	설명	기본값
PI_WECHAT_DEBUG	1로 설정 시 디버그 로그 활성화	꺼짐
PI_WECHAT_DEBUG_FILE	디버그 로그 경로	~/.pi/agent/wechat-assistant/debug.log
PI_WECHAT_IMAGE_BATCH_WAIT_MS	이미지 배치 대기 시간	8000
PI_WECHAT_IMAGE_MAX_BYTES	이미지 크기 제한	52428800 (50 MB)

설정 파일

~/.pi/agent/wechat-assistant/
├── credentials.json   # 로그인 자격 증명 (권한 600)
├── config.json        # 자동 시작, 이미지 제한
└── session.lock       # 배타적 잠금 파일

아키텍처

WeChat  ⇄  pi TUI 세션  ⇄  AI 모델 + 도구

• WeChat 메시지는 iLink Bot API 롱 폴링으로 가져옴
• 수신 메시지는 pi.sendUserMessage() 로 현재 pi 세션에 주입
• TUI에서 입력하면 WeChat 측에 미리보기 전송
• AI 응답은 증분 전송 (message_end 마다), agent_end 에서 나머지 보완
• /wechat start 를 실행한 TUI 세션만 연결 유지

FAQ

WeChat에서 응답이 없음? /wechat status 로 상태 확인. 세션 만료 시 /wechat login --force 실행.

"다른 pi 인스턴스가 사용 중" 표시? 다른 TUI 세션이 잠금을 유지 중. 해당 세션에서 /wechat stop 실행.

이미지가 바로 처리되지 않는 이유? 배치 처리를 위해 최대 8초 대기. 여러 이미지 연속 전송 후 텍스트로 보충 가능. 첫 이미지는 즉시 확인 응답, 대기 중 텍스트 전송 시 즉시 처리.

개발

git clone https://github.com/shenjiecode/pi-wechat-assistant.git
cd pi-wechat-assistant
npm install
npm run typecheck

# 빠른 테스트
pi -e ./src/index.ts

릴리스

npm version patch   # package.json 업데이트, 커밋, 태그 생성
git push --follow-tags   # CI → npm 게시 + GitHub Release 트리거

라이선스

MIT