docs: add gewechat docs (#146)

hanfangyuan4396 · Dec 4, 2024 · fb05202 · fb05202
1 parent 05de411
commit fb05202
Show file tree

Hide file tree

Showing 5 changed files with 185 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -40,13 +40,59 @@ Dify接入微信生态的**详细教程**请查看文章 [**手摸手教你把 D
 
 
 # 最新功能
-## 1. 支持企业微信个人号（仅支持windows系统）
+## 1. 支持gewechat登录微信
+基于[Gewechat](https://github.com/Devo919/Gewechat)项目实现的微信个人号通道,使用ipad协议登录,相比itchat协议更稳定。
+
+> 1. gewechat要求必须搭建服务到**同省服务器**或者电脑里方可正常使用
+> 2. 此项目仅用于个人娱乐场景，请勿用于任何商业场景
+
+### 1.1 快速启动gewechat机器人
+
+#### 部署gewechat服务
+
+```bash
+# 从阿里云镜像仓库拉取(国内)
+docker pull registry.cn-chengdu.aliyuncs.com/tu1h/wechotd:alpine
+docker tag registry.cn-chengdu.aliyuncs.com/tu1h/wechotd:alpine gewe
+
+# 创建数据目录并启动服务
+mkdir -p gewechat/data  
+docker run -itd -v gewechat/data:/root/temp -p 2531:2531 -p 2532:2532 --restart=always --name=gewe gewe
+```
+
+#### 配置dify-on-wechat
+
+gewechat相关配置如下，注意**channel_type设置为gewechat**
+
+```bash 
+{
+    "channel_type": "gewechat",  # 通道类型设置为gewechat    
+    "gewechat_token": "",        # 首次登录可留空,自动获取
+    "gewechat_app_id": "",       # 首次登录可留空,自动获取
+    "gewechat_base_url": "http://本机ip:2531/v2/api",  # gewechat服务API地址
+    "gewechat_callback_url": "http://本机ip:9919/v2/api/callback/collect", # 回调地址
+    "gewechat_download_url": "http://本机ip:2532/download" # 文件下载地址
+}
+```
+**请务必查看详细配置**： [gewechat接入文档](./docs/gewechat/README.md)
+
+#### 启动机器人
+
+```bash
+python app.py
+```
+启动成功后，可以看到如下日志信息，注意token和appid会**自动保存**到config.json，无需手动保存
+
+![gewechat_login](./docs/gewechat/gewechat_login.jpg)
+
+
+## 2. 支持企业微信个人号（仅支持windows系统）
 ![wework](./docs/images/wework.jpg)
 
 > 1. 有**封号风险**，请使用企业微信**小号**测试
 > 2. 在登录旧版本的企业微信时可能会出现企业微信版本过低，无法登录情况，参考[issue1525](https://github.com/zhayujie/chatgpt-on-wechat/issues/1525)，请尝试更换其他企业微信号重试
 
-### 1.1 快速启动企业微信个人号机器人
+### 2.1 快速启动企业微信个人号机器人
 
 #### 安装指定版本企业微信
 
@@ -111,32 +157,32 @@ python app.py
 [INFO][2024-04-30 21:17:05][wework_channel.py:224] - wework程序初始化完成········
 ```
 
-## 2. 集成[JinaSum](https://github.com/hanfangyuan4396/jina_sum)插件
+## 3. 集成[JinaSum](https://github.com/hanfangyuan4396/jina_sum)插件
 使用Jina Reader和ChatGPT支持总结公众号、小红书、知乎等分享卡片链接，配置详情请查看[JinaSum](https://github.com/hanfangyuan4396/jina_sum)
 
 ![plugin-jinasum-1](./plugins/jina_sum/docs/images/wechat_mp.jpg)
 ![plugin-jinasum-1](./plugins/jina_sum/docs/images/red.jpg)
 
-## 3. 新增[CustomDifyApp](https://github.com/hanfangyuan4396/dify-on-wechat/tree/master/plugins/custom_dify_app)插件
+## 4. 新增[CustomDifyApp](https://github.com/hanfangyuan4396/dify-on-wechat/tree/master/plugins/custom_dify_app)插件
 支持根据群聊名称关键词自动切换不同的Dify应用，也支持为单聊配置专门的Dify应用。
 
 例如，在与AI助手进行私聊时，自动调用企业内部员工助手Dify应用；在xx平台技术支持群中@AI助手时，则自动切换至该平台的技术支持Dify应用。
 
 配置详情请查看 [CustomDifyApp](https://github.com/hanfangyuan4396/dify-on-wechat/tree/master/plugins/custom_dify_app)
 
-## 4. 支持Dify Chatflow & Workflow
+## 5. 支持Dify Chatflow & Workflow
 dify官网已正式上线工作流模式，可以导入本项目下的[dsl文件](./dsl/chat-workflow.yml)快速创建工作流进行测试。工作流输入变量名称十分灵活，对于**工作流类型**的应用，本项目**约定工作流的输入变量命名为`query`**，**输出变量命名为`text`**。
 
 (ps: 感觉工作流类型应用不太适合作为聊天机器人，现在它还没有会话的概念，需要自己管理上下文。但是它可以调用各种工具，通过http请求和外界交互，适合执行业务逻辑复杂的任务；它可以导入导出工作流dsl文件，方便分享移植。也许以后dsl文件+配置文件就可以作为本项目的一个插件。)
-## 5. 支持COZE API
+## 6. 支持COZE API
 
 ![image-5](./docs/images/image5.jpg)
 
 ![image-6](./docs/images/image6.jpg)
 
 
 
-### 5.1 如何快速启动coze微信机器人
+### 6.1 如何快速启动coze微信机器人
 
 - 请参照**快速开始**步骤克隆源码并安装依赖
 
@@ -169,7 +215,7 @@ python3 app.py                                    # windows环境下该命令通
 
 特别感谢 [**@绛烨**](https://github.com/jiangye520) 提供内测coze api key
 
-## 6. 支持dify voice
+## 7. 支持dify voice
 
 dify语音相关配置如下，另外需要在dify应用中开启语音转文字以及文字转语音功能，注意语音功能需要**安装ffmpeg依赖**
 
@@ -187,6 +233,7 @@ dify语音相关配置如下，另外需要在dify应用中开启语音转文字
 ```
 
 # 更新日志
+- 2024/12/04 新增 [gewechat](https://github.com/Devo919/Gewechat) 通道，相比itchat更稳定。
 - 2024/10/01 新增插件CustomDifyApp与GroupAtAutoreply，CustomDifyApp支持根据群聊名称关键词自动切换不同的Dify应用，GroupAtAutoreply支持群聊艾特自动回复，贡献者[**blankbro**](https://github.com/blankbro)
 - 2024/09/18 支持dify voice
 - 2024/08/09 dify chatbot类型应用支持解析markdown格式响应，分别发送文本、图片和文件

diff --git a/channel/gewechat/gewechat_channel.py b/channel/gewechat/gewechat_channel.py
@@ -73,13 +73,13 @@ def startup(self):
         if not callback_url:
             logger.error("[gewechat] callback_url is not set, unable to start callback server")
             return
-        
+
         # 设置回调地址，{ "ret": 200, "msg": "操作成功" }
         callback_resp = self.client.set_callback(self.token, callback_url)
         if callback_resp.get("ret") != 200:
             logger.error(f"[gewechat] set callback failed: {callback_resp}")
             return
-        
+
         # 从回调地址中解析出端口与url path，启动回调服务器  
         parsed_url = urlparse(callback_url)
         path = parsed_url.path

diff --git a/docs/gewechat/README.md b/docs/gewechat/README.md
@@ -0,0 +1,128 @@
+# 1. gewechat channel简介
+
+Gewechat channel是基于[Gewechat](https://github.com/Devo919/Gewechat)项目实现的微信个人号通道，使用ipad协议登录，能获取到wxid，能发送语音条消息，相比itchat协议更稳定。
+
+api文档地址为：[gewechat api](https://apifox.com/apidoc/shared-69ba62ca-cb7d-437e-85e4-6f3d3df271b1/api-197179336)
+
+# 2. gewechat 服务部署教程
+
+gewechat 服务需要自行部署，[dify-on-wechat](https://github.com/hanfangyuan4396/dify-on-wechat) 项目只负责对接gewechat服务，请参考下方教程部署gewechat服务。
+
+## 2.1 下载镜像
+
+感谢gewechat交流群中的大佬 `@1H` 重构了镜像,让gewe镜像不依赖cgroup和docker --privilege,可以在更高版本的ubuntu、debian以及macos系统上运行。
+
+```bash
+# 从阿里云镜像仓库拉取(国内)
+docker pull registry.cn-chengdu.aliyuncs.com/tu1h/wechotd:alpine
+docker tag registry.cn-chengdu.aliyuncs.com/tu1h/wechotd:alpine gewe
+
+# 或从GitHub镜像仓库拉取
+docker pull ghcr.io/tu1h/wechotd/wechotd:alpine
+docker tag ghcr.io/tu1h/wechotd/wechotd:alpine gewe
+```
+
+## 2.2 使用docker启动
+
+```bash
+mkdir -p gewechat/data  
+docker run -itd -v gewechat/data:/root/temp -p 2531:2531 -p 2532:2532 --restart=always --name=gewe gewe
+```
+
+## 2.3 使用docker compose启动
+
+首先创建必要的数据目录:
+
+```bash
+mkdir -p gewechat/data
+```
+
+创建 `docker-compose.yml` 文件:
+
+```yaml
+version: '3'
+services:
+  gewechat:
+    image: gewe
+    container_name: gewe
+    volumes:
+      - ./gewechat/data:/root/temp
+    ports:
+      - "2531:2531"
+      - "2532:2532"
+    restart: always
+```
+
+运行:
+```bash
+docker compose up -d
+```
+
+## 2.4 成功日志
+
+看到如下日志，表示gewechat服务启动成功
+
+![gewechat_service_success](./gewechat_service_success.jpg)
+
+# 3. 使用dify-on-wechat对接gewechat服务
+
+## 3.1 gewechat相关参数配置
+
+在config.json中需要配置以下gewechat相关的参数：
+
+```bash
+{
+    "channel_type": "gewechat"   # 通道类型，请设置为gewechat    
+    "gewechat_token": "",        # gewechat服务的token，用于接口认证
+    "gewechat_app_id": "",       # gewechat服务的应用ID
+    "gewechat_base_url": "http://本机ip:2531/v2/api",  # gewechat服务的API基础URL
+    "gewechat_callback_url": "http://本机ip:9919/v2/api/callback/collect", # 回调URL，用于接收消息
+    "gewechat_download_url": "http://本机ip:2532/download", # 文件下载URL
+}
+```
+
+参数说明：
+- `gewechat_token`: gewechat服务的认证token，首次登录时，可以留空，启动dify-on-wechat服务时，会**自动获取token**并**自动保存到config.json**中
+- `gewechat_app_id`: gewechat服务分配的设备ID，首次登录时，可以留空，启动dify-on-wechat服务时，会**自动获取appid**并**自动保存到config.json**中
+- `gewechat_base_url`: gewechat服务的API基础地址，请根据实际情况配置，如果gewechat服务与dify-on-wechat服务部署在同一台机器上，可以配置为`http://本机ip:2531/v2/api`
+- `gewechat_callback_url`: 接收gewechat消息的回调地址，请根据实际情况配置，如果gewechat服务与dify-on-wechat服务部署在同一台机器上，可以配置为`http://本机ip:9919/v2/api/callback/collect`
+- `gewechat_download_url`: 文件下载地址，用于下载语音、图片等文件，请根据实际部署情况配置，如果gewechat服务与dify-on-wechat服务部署在同一台机器上，可以配置为`http://本机ip:2532/download`
+
+注意：请确保您的回调地址(callback_url)，即dify-on-wechat启动的回调服务可以被gewechat服务正常访问到。如果您使用Docker部署，需要注意网络配置，确保容器之间可以正常通信。
+
+## 3.2 dify相关参数配置
+
+在config.json中需要配置以下dify相关参数：
+
+```json
+{
+  "dify_api_base": "https://api.dify.ai/v1",    // dify base url
+  "dify_api_key": "app-xxx",                    // dify api key
+  "dify_app_type": "chatbot",                   // dify应用类型,对应聊天助手
+  "channel_type": "gewechat",                   // 通道类型设置为gewechat
+  "model": "dify",                              // 模型名称设置为dify
+  "single_chat_prefix": [""],                   // 私聊触发前缀
+  "single_chat_reply_prefix": "",               // 私聊回复前缀
+  "group_chat_prefix": ["@bot"],                // 群聊触发前缀
+  "group_name_white_list": ["ALL_GROUP"],       // 允许响应的群组
+}
+```
+
+关于dify_api_base、dify_api_key等参数的获取方法,请参考文章 [手摸手教你把 Dify 接入微信生态](https://docs.dify.ai/v/zh-hans/learn-more/use-cases/dify-on-wechat)。
+
+## 3.3 启动dify-on-wechat服务
+
+完成上述配置后，你需要确保gewechat服务已正常启动，dify-on-wechat的依赖已安装(见 [dify-on-wechat项目README](https://github.com/hanfangyuan4396/dify-on-wechat) 或 [手摸手教你把 Dify 接入微信生态](https://docs.dify.ai/v/zh-hans/learn-more/use-cases/dify-on-wechat) )，然后运行以下命令启动服务:
+
+```bash
+python app.py
+```
+启动成功后，可以看到如下日志信息，注意token和appid会自动保存到config.json，无需手动保存
+
+![gewechat_login](./gewechat_login.jpg)
+
+# 4. gewechat_channel 服务的限制
+1. gewechat 要求必须搭建服务到同省服务器或者电脑里方可正常使用，即登录微信的手机与gewechat服务必须在同一省
+2. gewechat 开源框架只支持下载接收到的图片，不支持下载文件
+3. gewechat_channel 目前暂时只支持接收文字消息，只支持发送文字消息与图片消息，后续支持的消息类型会逐步完善
+4. 此项目仅用于个人娱乐场景，请勿用于任何商业场景
diff --git a/docs/gewechat/gewechat_login.jpg b/docs/gewechat/gewechat_login.jpg
diff --git a/docs/gewechat/gewechat_service_success.jpg b/docs/gewechat/gewechat_service_success.jpg