first commit

docs/pi-im-agent.md

@@ -0,0 +1,219 @@
+# Pi Agent + IM 使用说明
+
+这份文档说明如何把当前项目作为 Pi agent 的运行壳，用 IM 作为外部通信渠道。
+
+## 目标链路
+
+```text
+外部 IM 消息 -> wechat-bot -> Pi agent -> IM 回复
+```
+
+当前已实现：
+
+- 微信 IM：扫码登录后接收/回复消息。
+- Pi agent：作为 `serve` 类型处理微信消息。
+- 本地微信数据：通过 OpenCLI `wx-cli` 访问聊天、群成员、统计和朋友圈缓存。
+- 飞书 IM：通过 `lark-cli` 登录、发消息、读消息、搜索消息。
+
+## 安装命令
+
+如果希望直接使用 `wb` 命令，在项目根目录执行：
+
+```sh
+npm link
+```
+
+也可以不用 `wb`，直接使用：
+
+```sh
+npm run start -- <command>
+```
+
+## 环境配置
+
+复制并编辑 `.env`：
+
+```sh
+cp .env.example .env
+```
+
+微信 + Pi 推荐配置：
+
+```env
+BOT_NAME='@你的微信昵称'
+ALIAS_WHITELIST='允许私聊你的好友备注'
+ROOM_WHITELIST='允许接入的群名'
+AUTO_REPLY_PREFIX=''
+
+WECHAT_DATA_DIR='.data/wechat'
+WECHAT_STORE_MESSAGES='true'
+
+PI_BIN='pi'
+PI_NPM_PACKAGE='@earendil-works/pi-coding-agent'
+PI_AGENT_ARGS='--print --no-session'
+```
+
+如果本机没有全局 `pi` 命令，可以先留空：
+
+```env
+PI_BIN=''
+```
+
+项目会通过 `npx --yes @earendil-works/pi-coding-agent` 调起 Pi，但每次冷启动会慢一些。
+
+## 微信扫码接入 Pi
+
+推荐命令：
+
+```sh
+wb agent --im wechat --agent pi
+```
+
+等价命令：
+
+```sh
+wb start --serve pi
+```
+
+或使用 npm：
+
+```sh
+npm run agent
+npm run start -- start --serve pi
+```
+
+启动后终端会展示微信二维码。扫码登录成功后，链路如下：
+
+```text
+微信扫码登录 -> Wechaty 收消息 -> 本地 JSONL 捕获 -> Pi 单轮 agent 回复 -> 微信 IM 发回
+```
+
+触发规则：
+
+- 私聊：发消息人必须在 `ALIAS_WHITELIST` 中。
+- 群聊：群名必须在 `ROOM_WHITELIST` 中，并且消息里需要 `@机器人昵称`。
+- 非文本消息不会进入 Pi 回复链路。
+
+## 微信内置分析命令
+
+微信聊天中可以直接发命令：
+
+```text
+/统计 群 XX群1
+/分析 群 XX群1
+/统计 好友 好友备注
+/分析 好友 好友备注
+```
+
+说明：
+
+- `/统计` 只读取本地 JSONL，不调用 AI。
+- `/分析` 会调用当前 agent 或 AI 服务，并把最近消息样本发给模型。
+- 隐私聊天建议优先使用本地模型或本地 Pi 配置。
+
+## 本地微信数据与朋友圈
+
+OpenCLI 的 `wx-cli` 可访问本机微信缓存数据：
+
+```sh
+wb wx init
+wb wx sessions
+wb wx history
+wb wx search
+wb wx contacts
+wb wx members
+wb wx stats
+wb wx favorites
+wb wx sns-feed
+wb wx sns-search
+wb wx sns-notifications
+```
+
+首次使用先执行：
+
+```sh
+wb wx init
+```
+
+查看 `wx-cli` 支持的完整命令：
+
+```sh
+wb wx help
+```
+
+## 飞书 IM
+
+飞书当前是 CLI 控制通道，可登录、读写和搜索消息：
+
+```sh
+wb lark login --no-wait
+wb lark status
+wb lark messages --chat-id oc_xxx
+wb lark search --query "关键词"
+wb lark send --chat-id oc_xxx --text "hello"
+```
+
+`--no-wait` 会返回 device-flow 授权链接/扫码信息。你完成授权后，再运行读写命令。
+
+当前飞书还不是实时事件通道；也就是说，飞书消息不会自动推给 Pi 回复。后续要实现飞书实时 agent，需要接入 Lark event consume，再把收到的消息转给 Pi。
+
+## Pi 透传命令
+
+直接调用 Pi：
+
+```sh
+wb pi -- --help
+wb pi -- --print "分析当前项目结构"
+```
+
+`PI_AGENT_ARGS` 控制 Pi 作为 IM 回复 agent 时的参数。默认：
+
+```env
+PI_AGENT_ARGS='--print --no-session'
+```
+
+这表示每条 IM 消息都是单轮非交互回复。如果希望沿用会话，可以去掉 `--no-session`，但要注意上下文和隐私数据会被 Pi session 保存。
+
+## 常见问题
+
+### 扫码后没有回复
+
+检查：
+
+- 私聊好友备注是否在 `ALIAS_WHITELIST`。
+- 群名是否在 `ROOM_WHITELIST`。
+- 群聊是否真的 `@` 了 `BOT_NAME`。
+- `.env` 中 `BOT_NAME` 是否形如 `@你的微信昵称`。
+- 当前消息是否为文本消息。
+
+### Pi 回复慢
+
+建议配置本机 Pi：
+
+```env
+PI_BIN='pi'
+```
+
+如果留空，项目会通过 `npx` 调起 Pi，首次执行和冷启动都会更慢。
+
+### 如何只分析，不自动回复
+
+使用命令行：
+
+```sh
+wb analyze --room "群名" --stats-only
+wb analyze --friend "好友备注" --stats-only
+```
+
+或调用 AI 深度分析：
+
+```sh
+wb analyze --room "群名" --serve pi
+```
+
+### 安全边界
+
+- 项目只处理本机已登录账号可见的数据。
+- 微信自动回复受白名单控制。
+- OpenCLI 远程执行默认关闭。
+- `/分析` 会把消息样本交给当前模型或 agent，处理隐私数据前请确认模型运行位置和配置。