diff --git a/channel/wechatcom_kf/README.md b/channel/wechatcom_kf/README.md index e74f3a78..933e6981 100644 --- a/channel/wechatcom_kf/README.md +++ b/channel/wechatcom_kf/README.md @@ -33,7 +33,7 @@ | 字段 | 来源 | 对应 CoW 配置项 | |---|---|---| | 企业ID(CorpId) | 「我的企业」最下方 | `wechatcom_corp_id` | -| Secret | 进入应用详情 → 复制 | `wechatcom_kf_secret` | +| Secret | 进入应用详情 → 点击「查看」(会推送到管理员手机端,在手机上查看) | `wechatcom_kf_secret` | | Token | 应用「接收消息 → 设置API接收」 | `wechatcom_kf_token` | | EncodingAESKey | 应用「接收消息 → 设置API接收」 | `wechatcom_kf_aes_key` | @@ -52,7 +52,12 @@ 进入 企业微信后台 → **微信客服** → 创建客服账号 → **将该账号绑定到上一步创建的企微自建应用**。 -绑定完成后,企业微信会给你一个客服访问链接 / 二维码,把它推给微信客户使用即可。 +绑定完成后,进入 **微信客服 → 微信客服账号详情** 页面,在「**接入链接**」一栏: + +- 「复制链接」可拿到形如 `https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be` 的访问链接 +- 「生成二维码」可拿到对应二维码 + +把链接或二维码推给微信客户使用即可。 ## 三、CoW 配置(`config.json`) @@ -64,22 +69,17 @@ "wechatcom_kf_secret": "<企微应用的 Secret>", "wechatcom_kf_token": "<接收消息 Token>", "wechatcom_kf_aes_key": "", - "wechatcom_kf_port": 9888, - - "wechatcom_kf_cursor_dir": "tmp" + "wechatcom_kf_port": 9888 } ``` | 字段 | 说明 | |---|---| | `wechatcom_corp_id` | 企业 ID,可与 `wechatcom_app` 共用 | -| `wechatcom_kf_secret` | **绑定到微信客服**的那个企微自建应用的 Secret(不是 wechatcomapp_secret) | +| `wechatcom_kf_secret` | **绑定到微信客服**的那个企微自建应用的 Secret | | `wechatcom_kf_token` | 该应用「接收消息」配置的 Token | | `wechatcom_kf_aes_key` | 该应用「接收消息」配置的 EncodingAESKey | -| `wechatcom_kf_port` | 监听端口,默认 `9888`(避开 `wechatcomapp_port=9898`) | -| `wechatcom_kf_cursor_dir` | `next_cursor` 持久化目录,默认 `tmp/` | - -> 首次启动(本地无 cursor 文件)会自动把 cursor 推进到"当前最新",跳过历史消息。否则微信客服会回放最近 14 天的消息把所有用户都骚扰一遍 —— 这个行为是固定的,没有配置开关。 +| `wechatcom_kf_port` | 监听端口,默认 `9888` | 也支持环境变量:`WECHATCOM_CORP_ID` / `WECHATCOM_KF_SECRET` / `WECHATCOM_KF_TOKEN` / `WECHATCOM_KF_AES_KEY`。 @@ -98,29 +98,7 @@ python app.py 回到企微后台「设置API接收」点击保存——会触发 `GET /wxkf/?...&echostr=...`,CoW 通过 `crypto.check_signature` 校验后返回明文 `echostr`,验证成功。 -## 五、与自建应用通道的运行差异 - -| 维度 | 自建应用 (`wechatcom_app`) | 微信客服 (`wechatcom_kf`) | -|---|---|---| -| 接收方式 | 回调直接 push,消息内容现成 | 回调只通知"有新消息",需调 `kf/sync_msg` 主动拉 | -| 接收方ID | `userid`(成员) | `external_userid`(外部用户)+ `open_kfid`(客服身份) | -| 发送接口 | `wechatpy` 内置封装 | 直接 POST `cgi-bin/kf/send_msg` | -| 端口 | 9898 | 9888 | -| 状态保存 | 无 | 必须持久化 `next_cursor`(本通道写本地 JSON) | - -## 六、cursor 持久化 - -`next_cursor` 是企微返回的"我上次拉到哪儿了"的书签。本通道把它存在 -`tmp/wechatcom_kf_cursors.json`(按 `open_kfid` 分键),重启不会丢。 - -**不要轻易删除该文件**。若删除,下次启动会触发"首次启动"逻辑,**自动**把 cursor 推进到最新位置,跳过历史消息。 - -## 七、多客服账号 - -一个企业可以创建多个客服账号(多个 `open_kfid`)共用一个企微应用。本通道 -**自动按 `open_kfid` 维护各自的 cursor**,无需为每个客服账号单独配置。 - -## 八、支持的回复类型 +## 五、支持的回复类型 | ReplyType | 是否支持 | 备注 | |---|---|---| @@ -130,7 +108,7 @@ python app.py | `VIDEO_URL` | ✅ | 通过临时素材接口上传 | | `FILE` | ✅ | | -## 九、参考文档 +## 六、参考文档 - [LinkAI 微信客服接入文档](https://docs.link-ai.tech/platform/link-app/wechat-customer-service) - [企业微信开放接口 - 微信客服 - 接收消息](https://developer.work.weixin.qq.com/document/path/94670) diff --git a/channel/wechatcom_kf/wechatcom_kf_channel.py b/channel/wechatcom_kf/wechatcom_kf_channel.py index b506b9e7..7a72728f 100644 --- a/channel/wechatcom_kf/wechatcom_kf_channel.py +++ b/channel/wechatcom_kf/wechatcom_kf_channel.py @@ -79,8 +79,9 @@ class WechatComKfChannel(ChatChannel): # corrupts URLs and triggers errcode 40014. self.client = WeChatClient(self.corp_id, self.secret) - cursor_dir = conf().get("wechatcom_kf_cursor_dir", "tmp") - cursor_path = os.path.join(cursor_dir, "wechatcom_kf_cursors.json") + # Cursor file is an internal implementation detail — fixed under + # the project's `tmp/` dir, not exposed as a user-facing config. + cursor_path = os.path.join("tmp", "wechatcom_kf_cursors.json") self.cursor_store = CursorStore(cursor_path) # ------------------------------------------------------------------ diff --git a/config.py b/config.py index 5e1c2fc9..19c78fdc 100644 --- a/config.py +++ b/config.py @@ -157,7 +157,6 @@ available_setting = { "wechatcom_kf_port": 9888, # 微信客服回调服务端口 "wechatcom_kf_secret": "", # 微信客服应用的secret "wechatcom_kf_aes_key": "", # 微信客服回调aes_key - "wechatcom_kf_cursor_dir": "tmp", # 拉取消息的cursor持久化目录(相对项目根) # 飞书配置 "feishu_port": 80, # 飞书bot监听端口,仅webhook模式需要 "feishu_app_id": "", # 飞书机器人应用APP Id