diff --git a/.gitignore b/.gitignore
index 0612e1e3..de10c0b7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,7 +32,6 @@ plugins/banwords/lib/__pycache__
!plugins/role
!plugins/keyword
!plugins/linkai
-!plugins/agent
!plugins/cow_cli
client_config.json
ref/
diff --git a/README.md b/README.md
index 951e5e37..1edf1d3f 100644
--- a/README.md
+++ b/README.md
@@ -1,918 +1,257 @@
-
+
English ] | [日本語 ]
+ [English] | [中文 ] | [日本語 ]
-**CowAgent** 是基于大模型的超级 AI 助理，能够主动思考和任务规划、操作计算机和外部资源、创造和执行 Skills、拥有长期记忆和知识库并不断成长，比 OpenClaw 更轻量和便捷。CowAgent 支持灵活切换多种模型，能处理文本、语音、图片、文件等多模态消息，可接入微信、飞书、钉钉、企微智能机器人、QQ、企微自建应用、微信公众号、网页中使用，7*24小时运行于你的个人电脑或服务器中。
+**CowAgent** is an open-source super AI assistant that proactively plans tasks, controls your computer and external services, creates and runs Skills, and grows alongside you through a personal knowledge base and long-term memory — a reference implementation of Agent Harness engineering.
+
+CowAgent is lightweight, easy to deploy, and built to extend. Plug in any major LLM provider and run it 24/7 on a personal computer or server, across the web and all major IM platforms.
- 🌐 官网 ·
- 📖 文档中心 ·
- 🚀 快速开始 ·
- 🧩 技能广场 ·
- ☁️ 在线体验
+ 🌐 Website ·
+ 📖 Docs ·
+ 🚀 Quick Start ·
+ 🧩 Skill Hub ·
+ ☁️ Try Online
+
-1. 语音配置
-
-+ 添加 `"speech_recognition": true` 将开启语音识别，默认使用 openai 的 whisper 模型识别为文字，同时以文字回复，该参数仅支持私聊 (注意由于语音消息无法匹配前缀，一旦开启将对所有语音自动回复，支持语音触发画图)；
-+ 添加 `"group_speech_recognition": true` 将开启群组语音识别，默认使用 openai 的 whisper 模型识别为文字，同时以文字回复，参数仅支持群聊 (会匹配 group_chat_prefix 和 group_chat_keyword, 支持语音触发画图)；
-+ 添加 `"voice_reply_voice": true` 将开启语音回复语音（同时作用于私聊和群聊）
-+ 使用 MiniMax TTS：设置 `"text_to_voice": "minimax"`，并配置 `minimax_api_key`；可通过 `"tts_voice_id"` 指定发音人（如 `English_Graceful_Lady`），`"text_to_voice_model"` 指定模型（如 `speech-2.8-hd`、`speech-2.8-turbo`）
-
-
-
-2. 其他配置
-
-+ `model`: 模型名称，Agent 模式下推荐使用 `deepseek-v4-flash`、`MiniMax-M2.7`、`glm-5.1`、`kimi-k2.6`、`qwen3.6-plus`、`claude-sonnet-4-6`、`gemini-3.1-pro-preview`，全部模型名称参考[common/const.py](https://github.com/zhayujie/CowAgent/blob/master/common/const.py)文件
-+ `character_desc`：普通对话模式下的机器人系统提示词。在 Agent 模式下该配置不生效，由工作空间中的文件内容构成。
-+ `subscribe_msg`：订阅消息，公众号和企业微信 channel 中请填写，当被订阅时会自动回复， 可使用特殊占位符。目前支持的占位符有{trigger_prefix}，在程序中它会自动替换成 bot 的触发词。
-
-
-
-3. LinkAI 配置
-
-+ `use_linkai`: 是否使用 LinkAI 接口，默认关闭，设置为 true 后可对接 LinkAI 平台，使用模型、知识库、工作流、插件等技能, 参考[接口文档](https://docs.link-ai.tech/platform/api/chat)
-+ `linkai_api_key`: LinkAI Api Key，可在 [控制台](https://link-ai.tech/console/interface) 创建
-
-
-注：全部配置项说明可在 [`config.py`](https://github.com/zhayujie/CowAgent/blob/master/config.py) 文件中查看。
-
-## 三、运行
-
-### 1.本地运行
-
-如果是个人计算机 **本地运行**，直接在项目根目录下执行：
-
-```bash
-cow start # 推荐，需先安装 Cow CLI
-python3 app.py # 或直接运行，windows 环境下该命令通常为 python app.py
-```
-
-运行后默认会启动 web 服务，可通过访问 `http://localhost:9899/chat` 在网页端对话。
-
-如果需要接入其他应用通道只需修改 `config.json` 配置文件中的 `channel_type` 参数，详情参考：[通道说明](#通道说明)。
-
-
-### 2.服务器部署
-
-推荐使用 `cow` 命令管理服务：
-
-```bash
-cow start # 后台启动
-cow stop # 停止服务
-cow restart # 重启服务
-cow status # 查看运行状态
-cow logs # 查看日志
-cow update # 拉取最新代码并重启
-```
-
-也可以使用传统方式后台运行：
-
-```bash
-nohup python3 app.py & tail -f nohup.out
-```
-
-此外，项目根目录下的 `run.sh` 脚本也支持一键管理服务，包括 `./run.sh start`、`./run.sh stop`、`./run.sh restart` 等命令，执行 `./run.sh help` 可查看全部用法。
-
-> 如果需要通过浏览器访问 Web 控制台，请确保服务器的 `9899` 端口已在防火墙或安全组中放行，建议仅对指定 IP 开放以保证安全。
-
-### 3.Docker部署
-
-使用 docker 部署无需下载源码和安装依赖，只需要获取 `docker-compose.yml` 配置文件并启动容器即可。Agent 模式下更推荐使用源码进行部署，以获得更多系统访问能力。
-
-> 前提是需要安装好 `docker` 及 `docker-compose`，安装成功后执行 `docker -v` 和 `docker-compose version` (或 `docker compose version`) 可查看到版本号。安装地址为 [docker官网](https://docs.docker.com/engine/install/) 。
-
-**(1) 下载 docker-compose.yml 文件**
+**Docker:**
```bash
curl -O https://cdn.link-ai.tech/code/cow/docker-compose.yml
+docker compose up -d
```
-下载完成后打开 `docker-compose.yml` 填写所需配置，例如 `CHANNEL_TYPE`、`OPEN_AI_API_KEY` 和等配置。
+Once started, open `http://localhost:9899` to access the **Web console** — your one-stop hub to chat with the Agent, configure models, connect channels, and install skills.
-**(2) 启动容器**
+> Deploying on a server? Set `web_host` to `0.0.0.0` in `config.json` to make the console reachable from outside, and set `web_password` to protect it. Don't forget to open port `9899` in your firewall or security group.
-在 `docker-compose.yml` 所在目录下执行以下命令启动容器：
+> 📖 Detailed guides: [Quick Start](https://docs.cowagent.ai/en/guide/quick-start) · [Install from Source](https://docs.cowagent.ai/en/guide/manual-install) · [Upgrade](https://docs.cowagent.ai/en/guide/upgrade)
+
+After installation, manage the service with the [cow CLI](https://docs.cowagent.ai/en/cli/index):
```bash
-sudo docker compose up -d # 若docker-compose为 1.X 版本，则执行 `sudo docker-compose up -d`
+cow start | stop | restart # service control
+cow status | logs # status and logs
+cow update # pull latest code and restart
+cow skill install # install a skill
+cow install-browser # install browser automation
```
-运行命令后，会自动取 [docker hub](https://hub.docker.com/r/zhayujie/chatgpt-on-wechat) 拉取最新 release 版本的镜像。当执行 `sudo docker ps` 能查看到 NAMES 为 chatgpt-on-wechat 的容器即表示运行成功。最后执行以下命令可查看容器的运行日志：
-
-```bash
-sudo docker logs -f chatgpt-on-wechat
-```
-
-> 如果需要通过浏览器访问 Web 控制台，请确保服务器的 `9899` 端口已在防火墙或安全组中放行，建议仅对指定 IP 开放以保证安全。
-
-## 模型说明
-
-推荐通过 Web 控制台在线管理模型配置，无需手动编辑文件，详见 [模型文档](https://docs.cowagent.ai/models)。以下是手动修改 `config.json` 配置模型的说明：
-
-
-DeepSeek
-
-1. API Key 创建：在 [DeepSeek 平台](https://platform.deepseek.com/api_keys) 创建 API Key
-
-2. 填写配置
-
-方式一：官方接入（推荐）：
-
-```json
-{
- "model": "deepseek-v4-flash",
- "deepseek_api_key": "sk-xxxxxxxxxxx"
-}
-```
-
- - `model`: 推荐填写 `deepseek-v4-flash`、`deepseek-v4-pro`
- - `deepseek_api_key`: DeepSeek 平台的 API Key
- - `deepseek_api_base`: 可选，默认为 `https://api.deepseek.com/v1`，可修改为第三方代理地址
-
-方式二：OpenAI 兼容方式接入：
-
-```json
-{
- "model": "deepseek-v4-flash",
- "bot_type": "openai",
- "open_ai_api_key": "sk-xxxxxxxxxxx",
- "open_ai_api_base": "https://api.deepseek.com/v1"
-}
-```
-
-
-
-
-MiniMax
-
-方式一：官方接入，配置如下(推荐)：
-
-```json
-{
- "model": "MiniMax-M2.7",
- "minimax_api_key": ""
-}
-```
- - `model`: 可填写 `MiniMax-M2.7、MiniMax-M2.7-highspeed、MiniMax-M2.5、MiniMax-M2.1、MiniMax-M2.1-lightning、MiniMax-M2、abab6.5-chat` 等
- - `minimax_api_key`：MiniMax 平台的 API-KEY，在 [控制台](https://platform.minimaxi.com/user-center/basic-information/interface-key) 创建
-
-方式二：OpenAI 兼容方式接入，配置如下：
-```json
-{
- "bot_type": "openai",
- "model": "MiniMax-M2.7",
- "open_ai_api_base": "https://api.minimaxi.com/v1",
- "open_ai_api_key": ""
-}
-```
-- `bot_type`: OpenAI 兼容方式
-- `model`: 可填 `MiniMax-M2.7、MiniMax-M2.7-highspeed、MiniMax-M2.5、MiniMax-M2.1、MiniMax-M2.1-lightning、MiniMax-M2`，参考[API文档](https://platform.minimaxi.com/document/%E5%AF%B9%E8%AF%9D?key=66701d281d57f38758d581d0#QklxsNSbaf6kM4j6wjO5eEek)
-- `open_ai_api_base`: MiniMax 平台 API 的 BASE URL
-- `open_ai_api_key`: MiniMax 平台的 API-KEY
-
-
-
-Claude
-
-1. API Key 创建：在 [Claude控制台](https://console.anthropic.com/settings/keys) 创建 API Key
-
-2. 填写配置
-
-```json
-{
- "model": "claude-sonnet-4-6",
- "claude_api_key": "YOUR_API_KEY"
-}
-```
- - `model`: 参考 [官方模型ID](https://docs.anthropic.com/en/docs/about-claude/models/overview#model-aliases) ，支持 `claude-sonnet-4-6、claude-opus-4-7、claude-opus-4-6、claude-sonnet-4-5、claude-sonnet-4-0、claude-opus-4-0、claude-3-5-sonnet-latest` 等
-
-
-
-Gemini
-
-API Key 创建：在 [控制台](https://aistudio.google.com/app/apikey?hl=zh-cn) 创建 API Key ，配置如下
-```json
-{
- "model": "gemini-3.1-flash-lite-preview",
- "gemini_api_key": ""
-}
-```
- - `model`: 参考[官方文档-模型列表](https://ai.google.dev/gemini-api/docs/models?hl=zh-cn)，支持 `gemini-3.1-flash-lite-preview、gemini-3.1-pro-preview、gemini-3-flash-preview、gemini-3-pro-preview` 等
-
-
-
-OpenAI
-
-1. API Key 创建：在 [OpenAI平台](https://platform.openai.com/api-keys) 创建 API Key
-
-2. 填写配置
-
-```json
-{
- "model": "gpt-5.4",
- "open_ai_api_key": "YOUR_API_KEY",
- "open_ai_api_base": "https://api.openai.com/v1",
- "bot_type": "openai"
-}
-```
-
- - `model`: 与 OpenAI 接口的 [model参数](https://platform.openai.com/docs/models) 一致，支持包括 gpt-5.4、gpt-5.4-mini、gpt-5.4-nano、o 系列、gpt-4.1 等模型，Agent 模式推荐使用 `gpt-5.4`、`gpt-5.4-mini`
- - `open_ai_api_base`: 如果需要接入第三方代理接口，可通过修改该参数进行接入
- - `bot_type`: 使用 OpenAI 相关模型时无需填写。当使用第三方代理接口接入 Claude 等非 OpenAI 官方模型时，该参数设为 `openai`
-
-
-
-智谱AI (GLM)
-
-方式一：官方接入，配置如下(推荐)：
-
-```json
-{
- "model": "glm-5.1",
- "zhipu_ai_api_key": ""
-}
-```
- - `model`: 可填 `glm-5.1、glm-5-turbo、glm-5、glm-4.7、glm-4-plus、glm-4-flash、glm-4-air、glm-4-airx、glm-4-long` 等, 参考 [glm 系列模型编码](https://bigmodel.cn/dev/api/normal-model/glm-4)
- - `zhipu_ai_api_key`: 智谱AI 平台的 API KEY，在 [控制台](https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys) 创建
-
-方式二：OpenAI 兼容方式接入，配置如下：
-```json
-{
- "bot_type": "openai",
- "model": "glm-5.1",
- "open_ai_api_base": "https://open.bigmodel.cn/api/paas/v4",
- "open_ai_api_key": ""
-}
-```
-- `bot_type`: OpenAI 兼容方式
-- `model`: 可填 `glm-5.1、glm-5-turbo、glm-5、glm-4.7、glm-4-plus、glm-4-flash、glm-4-air、glm-4-airx、glm-4-long` 等
-- `open_ai_api_base`: 智谱AI 平台的 BASE URL
-- `open_ai_api_key`: 智谱AI 平台的 API KEY
-
-
-
-通义千问 (Qwen)
-
-方式一：官方 SDK 接入，配置如下(推荐)：
-
-```json
-{
- "model": "qwen3.6-plus",
- "dashscope_api_key": "sk-qVxxxxG"
-}
-```
- - `model`: 可填写 `qwen3.6-plus、qwen3.5-plus、qwen3-max、qwen-max、qwen-plus、qwen-turbo、qwen-long、qwq-plus` 等
- - `dashscope_api_key`: 通义千问的 API-KEY，参考 [官方文档](https://bailian.console.aliyun.com/?tab=api#/api) ，在 [百炼控制台](https://bailian.console.aliyun.com/?tab=model#/api-key) 创建
-
-方式二：OpenAI 兼容方式接入，配置如下：
-```json
-{
- "bot_type": "openai",
- "model": "qwen3.6-plus",
- "open_ai_api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- "open_ai_api_key": "sk-qVxxxxG"
-}
-```
-- `bot_type`: OpenAI 兼容方式
-- `model`: 支持官方所有模型，参考[模型列表](https://help.aliyun.com/zh/model-studio/models?spm=a2c4g.11186623.0.0.78d84823Kth5on#9f8890ce29g5u)
-- `open_ai_api_base`: 通义千问 API 的 BASE URL
-- `open_ai_api_key`: 通义千问的 API-KEY
-
-
-
-豆包 (Doubao)
-
-1. API Key 创建：在 [火山方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/apikey) 创建API Key
-
-2. 填写配置
-
-```json
-{
- "model": "doubao-seed-2-0-code-preview-260215",
- "ark_api_key": "YOUR_API_KEY"
-}
-```
- - `model`: 可填写 `doubao-seed-2-0-code-preview-260215、doubao-seed-2-0-pro-260215、doubao-seed-2-0-lite-260215、doubao-seed-2-0-mini-260215` 等
- - `ark_api_key`: 火山方舟平台的 API Key，在 [控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/apikey) 创建
- - `ark_base_url`: 可选，默认为 `https://ark.cn-beijing.volces.com/api/v3`
-
-
-
-Kimi (Moonshot)
-
-方式一：官方接入，配置如下：
-
-```json
-{
- "model": "kimi-k2.6",
- "moonshot_api_key": ""
-}
-```
- - `model`: 可填写 `kimi-k2.6、kimi-k2.5、kimi-k2、moonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k`
- - `moonshot_api_key`: Moonshot 的 API-KEY，在 [控制台](https://platform.moonshot.cn/console/api-keys) 创建
-
-方式二：OpenAI 兼容方式接入，配置如下：
-```json
-{
- "bot_type": "openai",
- "model": "kimi-k2.6",
- "open_ai_api_base": "https://api.moonshot.cn/v1",
- "open_ai_api_key": ""
-}
-```
-- `bot_type`: OpenAI 兼容方式
-- `model`: 可填写 `kimi-k2.6、kimi-k2.5、kimi-k2、moonshot-v1-8k、moonshot-v1-32k、moonshot-v1-128k`
-- `open_ai_api_base`: Moonshot 的 BASE URL
-- `open_ai_api_key`: Moonshot 的 API-KEY
-
-
-
-ModelScope
-
-```json
-{
- "bot_type": "modelscope",
- "model": "Qwen/QwQ-32B",
- "modelscope_api_key": "your_api_key",
- "modelscope_base_url": "https://api-inference.modelscope.cn/v1/chat/completions",
- "text_to_image": "MusePublic/489_ckpt_FLUX_1"
-}
-```
-
-- `bot_type`: modelscope 接口格式
-- `model`: 参考[模型列表](https://www.modelscope.cn/models?filter=inference_type&page=1)
-- `modelscope_api_key`: 参考 [官方文档-访问令牌](https://modelscope.cn/docs/accounts/token) ，在 [控制台](https://modelscope.cn/my/myaccesstoken)
-- `modelscope_base_url`: modelscope 平台的 BASE URL
-- `text_to_image`: 图像生成模型，参考[模型列表](https://www.modelscope.cn/models?filter=inference_type&page=1)
-
-
-
-LinkAI
-
-1. API Key 创建：在 [LinkAI平台](https://link-ai.tech/console/interface) 创建 API Key
-
-2. 填写配置
-
-```json
-{
- "model": "gpt-5.4-mini",
- "use_linkai": true,
- "linkai_api_key": "YOUR API KEY"
-}
-```
-
-+ `use_linkai`: 是否使用 LinkAI 接口，默认关闭，设置为 true 后可对接 LinkAI 平台的模型，并使用知识库、工作流、数据库、插件等丰富的 Agent 技能
-+ `linkai_api_key`: LinkAI 平台的 API Key，可在 [控制台](https://link-ai.tech/console/interface) 中创建
-+ `model`: [模型列表](https://link-ai.tech/console/models)中的全部模型均可使用
-
-
-
-Azure
-
-1. API Key 创建：在 [Azure平台](https://oai.azure.com/) 创建 API Key
-
-2. 填写配置
-
-```json
-{
- "model": "",
- "use_azure_chatgpt": true,
- "open_ai_api_key": "",
- "open_ai_api_base": "",
- "azure_deployment_id": "",
- "azure_api_version": "2025-01-01-preview"
-}
-```
-
- - `model`: 留空即可
- - `use_azure_chatgpt`: 设为 true
- - `open_ai_api_key`: Azure 平台的密钥
- - `open_ai_api_base`: Azure 平台的 BASE URL
- - `azure_deployment_id`: Azure 平台部署的模型名称
- - `azure_api_version`: api 版本以及以上参数可以在部署的 [模型配置](https://oai.azure.com/resource/deployments) 界面查看
-
-
-
-百度千帆 / ERNIE
-
-方式一：官方接入（推荐），配置如下：
-
-```json
-{
- "model": "ernie-5.1",
- "qianfan_api_key": "",
- "qianfan_api_base": "https://qianfan.baidubce.com/v2"
-}
-```
-
- - `model`: 默认推荐填写 `ernie-5.1`（多模态，可直接识图），也可填写 `ernie-5.0`、`ernie-x1.1`、`ernie-4.5-turbo-128k`、`ernie-4.5-turbo-32k`；当主模型为纯文本 ERNIE 时，Vision 工具会自动 fallback 到 `ernie-4.5-turbo-vl`
- - `qianfan_api_key`: 百度千帆 API Key，通常以 `bce-v3/` 开头，可在百度智能云控制台创建
- - `qianfan_api_base`: 可选，默认为 `https://qianfan.baidubce.com/v2`
-
-方式二：OpenAI 兼容方式接入，配置如下：
-```json
-{
- "bot_type": "openai",
- "model": "ernie-5.1",
- "open_ai_api_base": "https://qianfan.baidubce.com/v2",
- "open_ai_api_key": ""
-}
-```
-- `bot_type`: OpenAI 兼容方式
-- `model`: 支持千帆平台上的 ERNIE 模型
-- `open_ai_api_base`: 百度千帆 OpenAI 兼容 API 的 BASE URL
-- `open_ai_api_key`: 百度千帆 API Key
-
-
-
-
-讯飞星火
-
-方式一：官方接入，配置如下：
-参考 [官方文档-快速指引](https://www.xfyun.cn/doc/platform/quickguide.html#%E7%AC%AC%E4%BA%8C%E6%AD%A5-%E5%88%9B%E5%BB%BA%E6%82%A8%E7%9A%84%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%BA%94%E7%94%A8-%E5%BC%80%E5%A7%8B%E4%BD%BF%E7%94%A8%E6%9C%8D%E5%8A%A1) 获取 `APPID、 APISecret、 APIKey` 三个参数
-
-```json
-{
- "model": "xunfei",
- "xunfei_app_id": "",
- "xunfei_api_key": "",
- "xunfei_api_secret": "",
- "xunfei_domain": "4.0Ultra",
- "xunfei_spark_url": "wss://spark-api.xf-yun.com/v4.0/chat"
-}
-```
- - `model`: 填 `xunfei`
- - `xunfei_domain`: 可填写 `4.0Ultra、generalv3.5、max-32k、generalv3、pro-128k、lite`
- - `xunfei_spark_url`: 填写参考 [官方文档-请求地址](https://www.xfyun.cn/doc/spark/Web.html#_1-1-%E8%AF%B7%E6%B1%82%E5%9C%B0%E5%9D%80) 的说明
-
-方式二：OpenAI 兼容方式接入，配置如下：
-```json
-{
- "bot_type": "openai",
- "model": "4.0Ultra",
- "open_ai_api_base": "https://spark-api-open.xf-yun.com/v1",
- "open_ai_api_key": ""
-}
-```
-- `bot_type`: OpenAI 兼容方式
-- `model`: 可填写 `4.0Ultra、generalv3.5、max-32k、generalv3、pro-128k、lite`
-- `open_ai_api_base`: 讯飞星火平台的 BASE URL
-- `open_ai_api_key`: 讯飞星火平台的[APIPassword](https://console.xfyun.cn/services/bm3) ，因模型而已
-
-
-
-Coding Plan
-
-Coding Plan 是各厂商推出的编程包月套餐，所有厂商均可通过 OpenAI 兼容方式接入：
-
-```json
-{
- "bot_type": "openai",
- "model": "模型名称",
- "open_ai_api_base": "厂商 Coding Plan API Base",
- "open_ai_api_key": "YOUR_API_KEY"
-}
-```
-
-目前支持阿里云、MiniMax、智谱 GLM、Kimi、火山引擎等厂商，各厂商详细配置请参考 [Coding Plan 文档](https://docs.cowagent.ai/models/coding-plan)。
-
-
-
-## 通道说明
-
-推荐通过 Web 控制台在线管理通道配置，无需手动编辑文件，详见 [通道文档](https://docs.cowagent.ai/channels/weixin)。以下为手动修改 `config.json` 配置通道的说明：
-
-支持同时可接入多个通道，配置时可通过逗号进行分割，例如 `"channel_type": "feishu,dingtalk"`。
-
-
-1. Weixin - 微信
-
-接入个人微信，扫码登录即可使用，支持文本、图片、语音、文件等消息收发。
-
-```json
-{
- "channel_type": "weixin"
-}
-```
-
-启动后终端会显示二维码，使用微信扫码授权即可，也可以在 Web 控制台的「通道」页面中扫码接入。登录凭证会自动保存至 `~/.weixin_cow_credentials.json`，下次启动无需重新扫码，如需重新登录删除该文件后重启即可。
-
-详细步骤和参数说明参考 [微信接入](https://docs.cowagent.ai/channels/weixin)
-
-
-
-
-2. Web
-
-项目启动后会默认运行 Web 控制台，配置如下：
-
-```json
-{
- "channel_type": "web",
- "web_host": "0.0.0.0",
- "web_password": "YOUR PASSWORD",
- "web_port": 9899
-}
-```
-
-- `web_host`: 监听地址，默认 `127.0.0.1`（仅本机），如需公网访问请改为 `0.0.0.0` 并设置密码
-- `web_port`: 默认为 9899，可按需更改，需要服务器防火墙和安全组放行该端口
-- `web_password`: 访问密码，留空则不启用密码保护。部署在公网环境时请务必设置
-- 如本地运行，启动后请访问 `http://localhost:9899` ；如服务器运行，请访问 `http://YOUR_IP:9899`
-> 注：请将上述 url 中的 ip 或者 port 替换为实际的值
-
-
-
-3. Feishu - 飞书
-
-飞书使用 WebSocket 长连接模式，无需公网 IP。详细步骤参考 [飞书接入](https://docs.cowagent.ai/channels/feishu)。
-
-**方式一：扫码一键创建（推荐）**
-
-启动 Cow 后打开 Web 控制台，**通道** → **接入通道** → 选择 **飞书** → 扫码创建。也支持 CLI 启动时在终端打印二维码。
-
-**方式二：手动配置**
-
-在飞书开放平台创建自建应用并配置权限后，将凭据填入 `config.json`：
-
-```json
-{
- "channel_type": "feishu",
- "feishu_app_id": "APP_ID",
- "feishu_app_secret": "APP_SECRET",
- "feishu_stream_reply": true
-}
-```
-
-- `feishu_stream_reply`：是否开启流式打字机回复，默认开启（需 `cardkit:card:write` 权限 + 飞书客户端 ≥ 7.20）
-
-
-
-
-4. DingTalk - 钉钉
-
-钉钉需要在开放平台创建智能机器人应用，将以下配置填入 `config.json`：
-
-```json
-{
- "channel_type": "dingtalk",
- "dingtalk_client_id": "CLIENT_ID",
- "dingtalk_client_secret": "CLIENT_SECRET"
-}
-```
-详细步骤和参数说明参考 [钉钉接入](https://docs.cowagent.ai/channels/dingtalk)
-
-
-
-5. WeCom Bot - 企微智能机器人
-
-企微智能机器人使用 WebSocket 长连接模式，无需公网 IP 和域名。详细步骤参考 [企微智能机器人接入](https://docs.cowagent.ai/channels/wecom-bot)。
-
-**方式一：扫码一键创建（推荐）**
-
-启动 Cow 后打开 Web 控制台，**通道** → **接入通道** → 选择 **企微智能机器人** → 使用企业微信扫码创建。
-
-**方式二：手动配置**
-
-在企业微信中创建智能机器人并选择**长连接模式**，记录 Bot ID 和 Secret 后填入 `config.json`：
-
-```json
-{
- "channel_type": "wecom_bot",
- "wecom_bot_id": "YOUR_BOT_ID",
- "wecom_bot_secret": "YOUR_SECRET"
-}
-```
-
-
-
-
-6. QQ - QQ 机器人
-
-QQ 机器人使用 WebSocket 长连接模式，无需公网 IP 和域名，支持 QQ 单聊、群聊和频道消息：
-
-```json
-{
- "channel_type": "qq",
- "qq_app_id": "YOUR_APP_ID",
- "qq_app_secret": "YOUR_APP_SECRET"
-}
-```
-详细步骤和参数说明参考 [QQ 机器人接入](https://docs.cowagent.ai/channels/qq)
-
-
-
-
-7. WeCom App - 企业微信应用
-
-企业微信自建应用接入需在后台创建应用并启用消息回调，配置示例：
-
-```json
-{
- "channel_type": "wechatcom_app",
- "wechatcom_corp_id": "CORPID",
- "wechatcomapp_token": "TOKEN",
- "wechatcomapp_port": 9898,
- "wechatcomapp_secret": "SECRET",
- "wechatcomapp_agent_id": "AGENTID",
- "wechatcomapp_aes_key": "AESKEY"
-}
-```
-详细步骤和参数说明参考 [企微自建应用接入](https://docs.cowagent.ai/channels/wecom)
-
-
-
-
-8. WeChat MP - 微信公众号
-
-本项目支持订阅号和服务号两种公众号，通过服务号（`wechatmp_service`）体验更佳。
-
-**个人订阅号（wechatmp）**
-
-```json
-{
- "channel_type": "wechatmp",
- "wechatmp_token": "TOKEN",
- "wechatmp_port": 80,
- "wechatmp_app_id": "APPID",
- "wechatmp_app_secret": "APPSECRET",
- "wechatmp_aes_key": ""
-}
-```
-
-**企业服务号（wechatmp_service）**
-
-```json
-{
- "channel_type": "wechatmp_service",
- "wechatmp_token": "TOKEN",
- "wechatmp_port": 80,
- "wechatmp_app_id": "APPID",
- "wechatmp_app_secret": "APPSECRET",
- "wechatmp_aes_key": ""
-}
-```
-
-详细步骤和参数说明参考 [微信公众号接入](https://docs.cowagent.ai/channels/wechatmp)
-
-
-
-
-9. Terminal - 终端
-
-修改 `config.json` 中的 `channel_type` 字段：
-
-```json
-{
- "channel_type": "terminal"
-}
-```
-
-运行后可在终端与机器人进行对话。
-
-
-
+A single Agent instance can serve multiple channels in parallel. Most channels can be onboarded right from the Web console.
-或直接在线咨询 [项目小助手](https://link-ai.tech/app/Kv2fXJcH) (知识库持续完善中，回复供参考)
+| Channel | Text | Image | File | Voice | Group |
+| --- | :-: | :-: | :-: | :-: | :-: |
+| [Web Console](https://docs.cowagent.ai/en/channels/web) (default) | ✅ | ✅ | ✅ | ✅ | |
+| [WeChat](https://docs.cowagent.ai/en/channels/weixin) | ✅ | ✅ | ✅ | ✅ | |
+| [Feishu / Lark](https://docs.cowagent.ai/en/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [DingTalk](https://docs.cowagent.ai/en/channels/dingtalk) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [WeCom Bot](https://docs.cowagent.ai/en/channels/wecom-bot) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [QQ](https://docs.cowagent.ai/en/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
+| [WeCom App](https://docs.cowagent.ai/en/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
+| [WeChat Official Account](https://docs.cowagent.ai/en/channels/wechatmp) | ✅ | ✅ | | ✅ | |
+| [Telegram](https://docs.cowagent.ai/en/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [Slack](https://docs.cowagent.ai/en/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
-# 🛠️ 开发
+> See the [Channels overview](https://docs.cowagent.ai/en/channels/index) for setup details.
-欢迎接入更多应用通道，参考 [飞书通道](https://github.com/zhayujie/CowAgent/blob/master/channel/feishu/feishu_channel.py) 新增自定义通道，实现接收和发送消息逻辑即可完成接入。同时欢迎贡献新的 Skills，向 [Skill Hub](https://skills.cowagent.ai/submit) 提交技能。
+
+
+
+ Long-term Memory · Three-tier architecture + Deep Dream
+
+
+ Knowledge Base · Auto-curated Markdown wiki
+
+
+
+
+ # search the marketplace
+/skill install # one-click install
+```
+
+Learn more: [Skills overview](https://docs.cowagent.ai/en/skills/index) · [Creating Skills](https://docs.cowagent.ai/en/skills/create).
+
+_ to ensure isolation
+
scheduler_session_id = f"scheduler_{receiver}_{task['id']}"
-
- # Build a natural language query for the Agent to execute the skill
- # Format: "Use skill-name to do something with params"
param_str = ", ".join([f"{k}={v}" for k, v in skill_params.items()])
query = f"Use {skill_name} skill"
if param_str:
query += f" with {param_str}"
-
- # Create context for Agent
+
context = Context(ContextType.TEXT, query)
context["receiver"] = receiver
context["isgroup"] = is_group
context["session_id"] = scheduler_session_id
-
- # Channel-specific setup
+
if channel_type == "web":
import uuid
request_id = f"scheduler_{task['id']}_{uuid.uuid4().hex[:8]}"
@@ -481,49 +484,48 @@ def _execute_skill_call(task: dict, agent_bridge):
elif channel_type == "wecom_bot":
context["msg"] = None
- # Use Agent to execute the skill
try:
- # Don't clear history - scheduler tasks use isolated session_id so they won't pollute user conversations
reply = agent_bridge.agent_reply(query, context=context, on_event=None, clear_history=False)
-
- if reply and reply.content:
- content = reply.content
-
- # Add prefix if specified
- if result_prefix:
- content = f"{result_prefix}\n\n{content}"
-
- # Send the result via channel
- from channel.channel_factory import create_channel
-
- try:
- channel = create_channel(channel_type)
- if channel:
- # For web channel, register request_id
- if channel_type == "web" and hasattr(channel, 'request_to_session'):
- req_id = context.get("request_id")
- if req_id:
- channel.request_to_session[req_id] = receiver
- logger.debug(f"[Scheduler] Registered request_id {req_id} -> session {receiver}")
-
- channel.send(Reply(ReplyType.TEXT, content), context)
- _remember_delivered_output(agent_bridge, task, channel_type, content)
- except Exception as e:
- logger.error(f"[Scheduler] Failed to send skill result: {e}")
-
- logger.info(f"[Scheduler] Task {task['id']} executed: skill result sent to {receiver}")
- else:
- logger.error(f"[Scheduler] Task {task['id']}: No result from skill execution")
-
except Exception as e:
logger.error(f"[Scheduler] Failed to execute skill via Agent: {e}")
import traceback
logger.error(f"[Scheduler] Traceback: {traceback.format_exc()}")
-
+ return False
+
+ if not (reply and reply.content):
+ logger.error(f"[Scheduler] Task {task['id']}: No result from skill execution")
+ return True
+
+ content = reply.content
+ if result_prefix:
+ content = f"{result_prefix}\n\n{content}"
+
+ from channel.channel_factory import create_channel
+ channel = create_channel(channel_type)
+ if not channel:
+ logger.error(f"[Scheduler] Failed to create channel: {channel_type}")
+ return False
+
+ if channel_type == "web" and hasattr(channel, 'request_to_session'):
+ req_id = context.get("request_id")
+ if req_id:
+ channel.request_to_session[req_id] = receiver
+
+ try:
+ channel.send(Reply(ReplyType.TEXT, content), context)
+ except Exception as e:
+ logger.error(f"[Scheduler] Failed to send skill result: {e}")
+ return False
+
+ _remember_delivered_output(agent_bridge, task, channel_type, content)
+ logger.info(f"[Scheduler] Task {task['id']} executed: skill result sent to {receiver}")
+ return True
+
except Exception as e:
logger.error(f"[Scheduler] Error in _execute_skill_call: {e}")
import traceback
logger.error(f"[Scheduler] Traceback: {traceback.format_exc()}")
+ return False
def attach_scheduler_to_tool(tool, context: Context = None):
diff --git a/agent/tools/scheduler/scheduler_service.py b/agent/tools/scheduler/scheduler_service.py
index dd5369cb..1f4bc6fb 100644
--- a/agent/tools/scheduler/scheduler_service.py
+++ b/agent/tools/scheduler/scheduler_service.py
@@ -52,7 +52,6 @@ class SchedulerService:
self.running = True
self.thread = threading.Thread(target=self._run_loop, daemon=True)
self.thread.start()
- logger.debug("[Scheduler] Service started")
def stop(self):
"""Stop the scheduler service"""
@@ -67,7 +66,7 @@ class SchedulerService:
def _run_loop(self):
"""Main scheduler loop"""
- logger.debug("[Scheduler] Scheduler loop started")
+ logger.info("[Scheduler] Scheduler loop started")
while self.running:
try:
@@ -84,12 +83,18 @@ class SchedulerService:
for task in tasks:
try:
- # Check if task is due
if self._is_task_due(task, now):
logger.info(f"[Scheduler] Executing task: {task['id']} - {task['name']}")
- self._execute_task(task)
-
- # Update next run time
+ ok = self._execute_task(task)
+ if not ok:
+ # Leave next_run_at as-is so the next loop retries.
+ # Cron tasks within the catch-up window will keep
+ # firing; beyond it _is_task_due will reschedule.
+ logger.warning(
+ f"[Scheduler] Task {task['id']} delivery failed, will retry next tick"
+ )
+ continue
+
next_run = self._calculate_next_run(task, now)
if next_run:
self.task_store.update_task(task['id'], {
@@ -97,7 +102,6 @@ class SchedulerService:
"last_run_at": now.isoformat()
})
else:
- # One-time task completed, remove it
self.task_store.delete_task(task['id'])
logger.info(f"[Scheduler] One-time task completed and removed: {task['id']}")
except Exception as e:
@@ -128,30 +132,35 @@ class SchedulerService:
try:
next_run = _parse_naive_local(next_run_str)
- # Check if task is overdue (e.g., service restart)
if next_run < now:
time_diff = (now - next_run).total_seconds()
-
- # If overdue by more than 5 minutes, skip this run and schedule next
- if time_diff > 300: # 5 minutes
- logger.warning(f"[Scheduler] Task {task['id']} is overdue by {int(time_diff)}s, skipping and scheduling next run")
-
- # For one-time tasks, remove them directly
- schedule = task.get("schedule", {})
- if schedule.get("type") == "once":
- self.task_store.delete_task(task['id'])
- logger.info(f"[Scheduler] One-time task {task['id']} expired, removed")
- return False
-
- # For recurring tasks, calculate next run from now
- next_next_run = self._calculate_next_run(task, now)
- if next_next_run:
- self.task_store.update_task(task['id'], {
- "next_run_at": next_next_run.isoformat()
- })
- logger.info(f"[Scheduler] Rescheduled task {task['id']} to {next_next_run}")
+ schedule = task.get("schedule", {})
+ schedule_type = schedule.get("type")
+
+ # Catch-up window: fire if we're within 10 minutes of the
+ # scheduled tick. Beyond that we'd rather skip than push a
+ # stale daily report to the user.
+ if time_diff <= 600:
+ return True
+
+ logger.warning(
+ f"[Scheduler] Task {task['id']} is overdue by {int(time_diff)}s, "
+ f"skipping and scheduling next run"
+ )
+
+ if schedule_type == "once":
+ self.task_store.delete_task(task['id'])
+ logger.info(f"[Scheduler] One-time task {task['id']} expired, removed")
return False
-
+
+ next_next_run = self._calculate_next_run(task, now)
+ if next_next_run:
+ self.task_store.update_task(task['id'], {
+ "next_run_at": next_next_run.isoformat()
+ })
+ logger.info(f"[Scheduler] Rescheduled task {task['id']} to {next_next_run}")
+ return False
+
return now >= next_run
except Exception as e:
logger.error(
@@ -213,20 +222,22 @@ class SchedulerService:
return None
- def _execute_task(self, task: dict):
+ def _execute_task(self, task: dict) -> bool:
"""
- Execute a task
-
- Args:
- task: Task dictionary
+ Execute a task.
+
+ Returns True if delivery succeeded (caller should advance state),
+ False if it failed (caller should keep next_run_at so the next
+ loop iteration retries). Callback may return None for legacy
+ behaviour, treated as success.
"""
try:
- # Call the execute callback
- self.execute_callback(task)
+ result = self.execute_callback(task)
+ return False if result is False else True
except Exception as e:
logger.error(f"[Scheduler] Error executing task {task['id']}: {e}")
- # Update task with error
self.task_store.update_task(task['id'], {
"last_error": str(e),
"last_error_at": datetime.now().isoformat()
})
+ return False
diff --git a/agent/tools/vision/vision.py b/agent/tools/vision/vision.py
index a1c3265f..498f3cd8 100644
--- a/agent/tools/vision/vision.py
+++ b/agent/tools/vision/vision.py
@@ -3,7 +3,7 @@ Vision tool - Analyze images using Vision API.
Supports local files (auto base64-encoded) and HTTP URLs.
Provider resolution:
- - tool.vision.model (if set) means "prefer this model first; fall back to
+ - tools.vision.model (if set) means "prefer this model first; fall back to
other configured providers if it fails". The model name is mapped to its
native provider (e.g. doubao-* → Doubao, kimi-* → Moonshot, gpt-* →
OpenAI/LinkAI). That provider is tried first, then the standard auto
@@ -53,14 +53,15 @@ _DISCOVERABLE_MODELS = [
("ark_api_key", const.DOUBAO, const.DOUBAO_SEED_2_PRO, "Doubao"),
("dashscope_api_key", const.QWEN_DASHSCOPE, const.QWEN36_PLUS, "DashScope"),
("claude_api_key", const.CLAUDEAPI, const.CLAUDE_4_6_SONNET, "Claude"),
- ("gemini_api_key", const.GEMINI, const.GEMINI_31_FLASH_LITE_PRE, "Gemini"),
+ ("gemini_api_key", const.GEMINI, const.GEMINI_35_FLASH, "Gemini"),
("qianfan_api_key", const.QIANFAN, const.ERNIE_45_TURBO_VL, "Qianfan"),
("zhipu_ai_api_key", const.ZHIPU_AI, const.GLM_4_7, "ZhipuAI"),
("minimax_api_key", const.MiniMax, const.MINIMAX_M2_7, "MiniMax"),
+ ("mimo_api_key", const.MIMO, const.MIMO_V2_5_PRO, "MiMo"),
]
# Model name prefix → discoverable provider display_name.
-# Used to auto-route tool.vision.model to its native provider.
+# Used to auto-route tools.vision.model to its native provider.
# Matched case-insensitively; longest prefix wins.
_MODEL_PREFIX_TO_PROVIDER = [
("doubao-", "Doubao"),
@@ -73,11 +74,29 @@ _MODEL_PREFIX_TO_PROVIDER = [
("glm-", "ZhipuAI"),
("minimax-", "MiniMax"),
("abab", "MiniMax"),
+ ("mimo-", "MiMo"),
]
# Model prefixes that natively belong to OpenAI / LinkAI (raw HTTP providers).
_OPENAI_MODEL_PREFIXES = ("gpt-", "o1-", "o3-", "o4-", "chatgpt-")
+# Maps the UI provider id (persisted in tools.vision.provider) to the internal
+# display name used in VisionProvider.name. Keep in sync with _DISCOVERABLE_MODELS
+# and the openai/linkai branches in _route_by_model_name.
+_PROVIDER_ID_TO_DISPLAY = {
+ "openai": "OpenAI",
+ "linkai": "LinkAI",
+ "moonshot": "Moonshot",
+ "doubao": "Doubao",
+ "dashscope": "DashScope",
+ "claudeAPI": "Claude",
+ "gemini": "Gemini",
+ "qianfan": "Qianfan",
+ "zhipu": "ZhipuAI",
+ "minimax": "MiniMax",
+ "mimo": "MiMo",
+}
+
@dataclass
class VisionProvider:
@@ -154,7 +173,7 @@ class Vision(BaseTool):
# Default model is only used as a last-resort placeholder for providers
# whose VisionProvider.model_override is None (e.g. raw OpenAI provider
- # when the user did not configure tool.vision.model).
+ # when the user did not configure tools.vision.model).
return self._call_with_fallback(providers, DEFAULT_MODEL, question, image_content)
def _call_with_fallback(self, providers: List[VisionProvider], model: str,
@@ -193,12 +212,12 @@ class Vision(BaseTool):
"""
Build an ordered list of providers to try.
- Semantics of `tool.vision.model`:
+ Semantics of `tools.vision.model`:
"Prefer this model first; fall back to other configured providers
if it fails."
Order:
- 1. The provider that natively serves `tool.vision.model` (if any
+ 1. The provider that natively serves `tools.vision.model` (if any
and its API key is configured) — using the user-specified model
name verbatim.
2. Auto-discovery chain as fallback:
@@ -211,13 +230,19 @@ class Vision(BaseTool):
are de-duplicated to avoid retrying the same endpoint twice.
"""
user_model = self._resolve_user_vision_model()
+ user_provider = self._resolve_user_vision_provider()
providers: List[VisionProvider] = []
- # Step 1: preferred provider derived from tool.vision.model
- if user_model:
+ # Step 1: preferred provider — explicit `tools.vision.provider`
+ # wins so custom model names can still be routed correctly. Falls
+ # through to model-name prefix inference when provider is unset.
+ preferred = None
+ if user_provider and user_model:
+ preferred = self._route_by_provider_id(user_provider, user_model)
+ if not preferred and user_model:
preferred = self._route_by_model_name(user_model)
- if preferred:
- providers.extend(preferred)
+ if preferred:
+ providers.extend(preferred)
# Step 2: auto-discovery chain as fallback
existing = {p.name for p in providers}
@@ -251,11 +276,11 @@ class Vision(BaseTool):
@staticmethod
def _resolve_user_vision_model() -> Optional[str]:
- """Read tool.vision.model from config; return None if unset/blank."""
- tool_conf = conf().get("tool", {})
- if not isinstance(tool_conf, dict):
+ """Read tools.vision.model (singular ``tool`` kept as runtime fallback)."""
+ tools_conf = conf().get("tools") or conf().get("tool") or {}
+ if not isinstance(tools_conf, dict):
return None
- vision_conf = tool_conf.get("vision", {})
+ vision_conf = tools_conf.get("vision", {})
if not isinstance(vision_conf, dict):
return None
m = vision_conf.get("model")
@@ -263,6 +288,24 @@ class Vision(BaseTool):
return m.strip()
return None
+ @staticmethod
+ def _resolve_user_vision_provider() -> Optional[str]:
+ """Read tools.vision.provider — the UI-persisted vendor id.
+
+ Lets users pin a vendor for custom model names that prefix-inference
+ can't recognize. Returns None when unset/blank.
+ """
+ tools_conf = conf().get("tools") or conf().get("tool") or {}
+ if not isinstance(tools_conf, dict):
+ return None
+ vision_conf = tools_conf.get("vision", {})
+ if not isinstance(vision_conf, dict):
+ return None
+ p = vision_conf.get("provider")
+ if isinstance(p, str) and p.strip():
+ return p.strip()
+ return None
+
@staticmethod
def _infer_provider_from_model(model_name: str) -> Optional[str]:
"""
@@ -279,6 +322,54 @@ class Vision(BaseTool):
return display_name
return None
+ def _route_by_provider_id(self, provider_id: str, user_model: str) -> Optional[List[VisionProvider]]:
+ """Route by the UI-persisted provider id.
+
+ Returns:
+ - [provider] : provider id is known and its key is configured.
+ - None : unknown provider id, or the bot can't be created.
+ Caller falls through to model-name-based routing.
+ """
+ display_name = _PROVIDER_ID_TO_DISPLAY.get(provider_id)
+ if not display_name:
+ return None
+
+ # OpenAI / LinkAI use raw HTTP providers, not the discoverable bot path.
+ if provider_id == "openai":
+ p = self._build_openai_provider(user_model)
+ return [p] if p else None
+ if provider_id == "linkai":
+ p = self._build_linkai_provider(user_model)
+ return [p] if p else None
+
+ # Discoverable bot-backed providers.
+ for config_key, bot_type, _default_model, name in _DISCOVERABLE_MODELS:
+ if name != display_name:
+ continue
+ api_key = conf().get(config_key, "")
+ if not api_key or not api_key.strip():
+ logger.warning(f"[Vision] tools.vision.provider='{provider_id}' "
+ f"but '{config_key}' is not configured. Falling back.")
+ return None
+ try:
+ from models.bot_factory import create_bot
+ bot = create_bot(bot_type)
+ if not hasattr(bot, 'call_vision'):
+ logger.warning(f"[Vision] '{display_name}' bot does not implement call_vision.")
+ return None
+ except Exception as e:
+ logger.warning(f"[Vision] Failed to create '{display_name}' bot: {e}")
+ return None
+ return [VisionProvider(
+ name=display_name,
+ api_key="",
+ api_base="",
+ model_override=user_model,
+ use_bot=True,
+ fallback_bot=bot,
+ )]
+ return None
+
def _route_by_model_name(self, user_model: str) -> Optional[List[VisionProvider]]:
"""
Try to build a provider list using the user-specified model name.
@@ -303,7 +394,7 @@ class Vision(BaseTool):
self._append_provider(providers, lambda: self._build_linkai_provider(user_model))
if providers:
return providers
- logger.warning(f"[Vision] tool.vision.model='{user_model}' looks like an OpenAI "
+ logger.warning(f"[Vision] tools.vision.model='{user_model}' looks like an OpenAI "
f"model but neither OPENAI_API_KEY nor LINKAI_API_KEY is configured.")
return None # fall through to auto
@@ -317,7 +408,7 @@ class Vision(BaseTool):
continue
api_key = conf().get(config_key, "")
if not api_key or not api_key.strip():
- logger.warning(f"[Vision] tool.vision.model='{user_model}' routes to "
+ logger.warning(f"[Vision] tools.vision.model='{user_model}' routes to "
f"'{display_name}' but '{config_key}' is not configured. "
f"Falling back to auto-discovery.")
return None # fall through to auto
@@ -452,8 +543,8 @@ class Vision(BaseTool):
if not self._main_bot_supports_vision(bot):
return None
- # Use the configured main model name; do NOT inject tool.vision.model
- # here, because by the time we reach this branch the tool.vision.model
+ # Use the configured main model name; do NOT inject tools.vision.model
+ # here, because by the time we reach this branch the tools.vision.model
# routing has already been attempted (and either matched the main bot
# or failed to find a provider).
main_model_name = conf().get("model") or None
diff --git a/agent/tools/web_search/web_search.py b/agent/tools/web_search/web_search.py
index 4c6d1e45..ca56567d 100644
--- a/agent/tools/web_search/web_search.py
+++ b/agent/tools/web_search/web_search.py
@@ -1,13 +1,27 @@
-"""
-Web Search tool - Search the web using Bocha or LinkAI search API.
-Supports two backends with unified response format:
- 1. Bocha Search (primary, requires BOCHA_API_KEY)
- 2. LinkAI Search (fallback, requires LINKAI_API_KEY)
+"""Web Search tool. Supports four backends with a unified response format:
+ - bocha (https://open.bochaai.com)
+ - zhipu (https://docs.bigmodel.cn/cn/guide/tools/web-search)
+ - qianfan (https://cloud.baidu.com/doc/qianfan/s/2mh4su4uy)
+ - linkai (https://link-ai.tech, fallback)
+
+Provider selection
+ - strategy 'auto' (default): pick the first configured provider in the
+ canonical order [bocha, zhipu, qianfan, linkai]. When the caller passes
+ an explicit `provider` it overrides the pick; an invalid/unconfigured
+ one silently falls back to the auto order.
+ - strategy 'fixed': use the configured provider; if its credential is
+ missing at call time, silently fall back to auto order (no card hint).
+
+Credentials
+ - bocha : tools.web_search.bocha_api_key -> env BOCHA_API_KEY
+ - zhipu : conf.zhipu_ai_api_key -> env ZHIPUAI_API_KEY
+ - qianfan : conf.qianfan_api_key -> env QIANFAN_API_KEY
+ - linkai : conf.linkai_api_key -> env LINKAI_API_KEY
"""
-import os
import json
-from typing import Dict, Any, Optional
+import os
+from typing import Any, Dict, List, Optional
import requests
@@ -16,12 +30,63 @@ from common.log import logger
from config import conf
-# Default timeout for API requests (seconds)
DEFAULT_TIMEOUT = 30
+# Canonical fallback order. Empirically ordered by Chinese real-time
+# quality + relevance: bocha (best overall), qianfan (best for hot news),
+# zhipu (strong on long-form articles), linkai (cloud aggregator, last
+# resort).
+PROVIDER_ORDER = ("bocha", "qianfan", "zhipu", "linkai")
+
+PROVIDER_LABELS = {
+ "bocha": "Bocha",
+ "zhipu": "Zhipu",
+ "qianfan": "Baidu Qianfan",
+ "linkai": "LinkAI",
+}
+
+
+def _tools_web_search_conf() -> dict:
+ """Return the tools.web_search config block (dict-like)."""
+ tools_cfg = conf().get("tools") or {}
+ if not isinstance(tools_cfg, dict):
+ return {}
+ block = tools_cfg.get("web_search") or {}
+ return block if isinstance(block, dict) else {}
+
+
+def _get_api_key(provider: str) -> str:
+ """Resolve API key for a provider, with conf -> env fallback."""
+ if provider == "bocha":
+ key = (_tools_web_search_conf().get("bocha_api_key") or "").strip()
+ return key or os.environ.get("BOCHA_API_KEY", "").strip()
+ if provider == "zhipu":
+ key = (conf().get("zhipu_ai_api_key") or "").strip()
+ return key or os.environ.get("ZHIPUAI_API_KEY", "").strip()
+ if provider == "qianfan":
+ key = (conf().get("qianfan_api_key") or "").strip()
+ return key or os.environ.get("QIANFAN_API_KEY", "").strip()
+ if provider == "linkai":
+ key = (conf().get("linkai_api_key") or "").strip()
+ return key or os.environ.get("LINKAI_API_KEY", "").strip()
+ return ""
+
+
+def configured_providers() -> List[str]:
+ """Return configured providers in canonical order."""
+ return [p for p in PROVIDER_ORDER if _get_api_key(p)]
+
+
+def _configured_strategy() -> str:
+ return (_tools_web_search_conf().get("strategy") or "auto").strip().lower()
+
+
+def _configured_provider() -> str:
+ return (_tools_web_search_conf().get("provider") or "").strip().lower()
+
class WebSearch(BaseTool):
- """Tool for searching the web using Bocha or LinkAI search API"""
+ """Tool for searching the web across multiple providers."""
name: str = "web_search"
description: str = "Search the web for real-time information. Returns titles, URLs, and snippets."
@@ -55,264 +120,368 @@ class WebSearch(BaseTool):
def __init__(self, config: dict = None):
self.config = config or {}
- self._backend = None # Will be resolved on first execute
@staticmethod
def is_available() -> bool:
- """Check if web search is available (at least one API key is configured)"""
- return bool(os.environ.get("BOCHA_API_KEY") or os.environ.get("LINKAI_API_KEY"))
+ """Tool is offered to the agent when at least one provider has a key."""
+ return bool(configured_providers())
- def _resolve_backend(self) -> Optional[str]:
- """
- Determine which search backend to use.
- Priority: Bocha > LinkAI
+ @classmethod
+ def get_json_schema(cls) -> dict:
+ """Augment the static schema with a `provider` field — only when the
+ user has ≥2 providers configured AND strategy is 'auto'. Otherwise
+ the backend picks silently and exposing the field would only waste
+ the agent's tokens."""
+ schema = {
+ "name": cls.name,
+ "description": cls.description,
+ "parameters": json.loads(json.dumps(cls.params)), # deep copy
+ }
+ if _configured_strategy() != "auto":
+ return schema
+ available = configured_providers()
+ if len(available) < 2:
+ return schema
- :return: 'bocha', 'linkai', or None
+ schema["parameters"]["properties"]["provider"] = {
+ "type": "string",
+ "enum": available,
+ "description": "Optional. Specifies the search backend. You may switch between providers when the user wants results from a particular source or from multiple sources.",
+ }
+ return schema
+
+ # ------------------------------------------------------------------
+ # Provider resolution
+ # ------------------------------------------------------------------
+
+ def _resolve_provider(self, requested: Optional[str]) -> Optional[str]:
+ """Pick a provider for this call.
+
+ Priority: caller-supplied (if configured) > fixed strategy (if
+ configured) > first configured in PROVIDER_ORDER. Silent fallback
+ when the desired one has no key.
"""
- if os.environ.get("BOCHA_API_KEY"):
- return "bocha"
- if os.environ.get("LINKAI_API_KEY"):
- return "linkai"
- return None
+ available = configured_providers()
+ if not available:
+ return None
+
+ if requested:
+ req = requested.strip().lower()
+ if req in available:
+ return req
+ logger.warning(f"[WebSearch] requested provider '{requested}' unavailable, falling back")
+
+ if _configured_strategy() == "fixed":
+ pinned = _configured_provider()
+ if pinned in available:
+ return pinned
+ if pinned:
+ logger.warning(f"[WebSearch] pinned provider '{pinned}' unavailable, falling back to auto")
+
+ return available[0]
+
+ @staticmethod
+ def _resolution_reason(requested: Optional[str], chosen: str) -> str:
+ """Human-readable explanation for why `chosen` won the resolver."""
+ if requested and requested.strip().lower() == chosen:
+ return "caller-requested"
+ strategy = _configured_strategy()
+ if strategy == "fixed" and _configured_provider() == chosen:
+ return "fixed-strategy"
+ return "auto-fallback"
+
+ # ------------------------------------------------------------------
+ # Entry point
+ # ------------------------------------------------------------------
def execute(self, args: Dict[str, Any]) -> ToolResult:
- """
- Execute web search
-
- :param args: Search parameters (query, count, freshness, summary)
- :return: Search results
- """
- query = args.get("query", "").strip()
+ query = (args.get("query") or "").strip()
if not query:
return ToolResult.fail("Error: 'query' parameter is required")
count = args.get("count", 10)
freshness = args.get("freshness", "noLimit")
summary = args.get("summary", False)
-
- # Validate count
if not isinstance(count, int) or count < 1 or count > 50:
count = 10
- # Resolve backend
- backend = self._resolve_backend()
- if not backend:
+ requested = args.get("provider")
+ provider = self._resolve_provider(requested)
+ if not provider:
return ToolResult.fail(
- "Error: No search API key configured. "
- "Please set BOCHA_API_KEY or LINKAI_API_KEY using env_config tool.\n"
- " - Bocha Search: https://open.bocha.cn\n"
- " - LinkAI Search: https://link-ai.tech"
+ "Error: No search provider configured. "
+ "Configure one of BOCHA_API_KEY / zhipu_ai_api_key / qianfan_api_key / linkai_api_key."
)
+ # Always log the routing decision so multi-provider deployments can
+ # tell at a glance which backend served any given query.
+ available = configured_providers()
+ reason = self._resolution_reason(requested, provider)
+ q_preview = query if len(query) <= 60 else (query[:57] + "...")
+ logger.info(
+ f"[WebSearch] provider={provider} reason={reason} "
+ f"available={list(available)} query={q_preview!r} count={count} freshness={freshness}"
+ )
+
try:
- if backend == "bocha":
+ if provider == "bocha":
return self._search_bocha(query, count, freshness, summary)
- else:
+ if provider == "zhipu":
+ return self._search_zhipu(query, count, freshness)
+ if provider == "qianfan":
+ return self._search_qianfan(query, count, freshness)
+ if provider == "linkai":
return self._search_linkai(query, count, freshness)
+ return ToolResult.fail(f"Error: Unknown provider '{provider}'")
except requests.Timeout:
return ToolResult.fail(f"Error: Search request timed out after {DEFAULT_TIMEOUT}s")
except requests.ConnectionError:
return ToolResult.fail("Error: Failed to connect to search API")
except Exception as e:
- logger.error(f"[WebSearch] Unexpected error: {e}", exc_info=True)
+ logger.error(f"[WebSearch] Unexpected error ({provider}): {e}", exc_info=True)
return ToolResult.fail(f"Error: Search failed - {str(e)}")
+ # ------------------------------------------------------------------
+ # Bocha
+ # ------------------------------------------------------------------
+
def _search_bocha(self, query: str, count: int, freshness: str, summary: bool) -> ToolResult:
- """
- Search using Bocha API
-
- :param query: Search query
- :param count: Number of results
- :param freshness: Time range filter
- :param summary: Whether to include summary
- :return: Formatted search results
- """
- api_key = os.environ.get("BOCHA_API_KEY", "")
- url = "https://api.bocha.cn/v1/web-search"
-
+ api_key = _get_api_key("bocha")
+ url = "https://api.bochaai.com/v1/web-search"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
- "Accept": "application/json"
+ "Accept": "application/json",
}
+ payload = {"query": query, "count": count, "freshness": freshness, "summary": summary}
- payload = {
- "query": query,
- "count": count,
- "freshness": freshness,
- "summary": summary
- }
+ logger.debug(f"[WebSearch] bocha: query='{query}', count={count}")
+ resp = requests.post(url, headers=headers, json=payload, timeout=DEFAULT_TIMEOUT)
- logger.debug(f"[WebSearch] Bocha search: query='{query}', count={count}")
+ if resp.status_code == 401:
+ return ToolResult.fail("Error: Invalid bocha API key.")
+ if resp.status_code == 403:
+ return ToolResult.fail("Error: bocha API — insufficient balance. Top up at https://open.bochaai.com")
+ if resp.status_code == 429:
+ return ToolResult.fail("Error: bocha API rate limit reached.")
+ if resp.status_code != 200:
+ return ToolResult.fail(f"Error: bocha API returned HTTP {resp.status_code}")
- response = requests.post(url, headers=headers, json=payload, timeout=DEFAULT_TIMEOUT)
-
- if response.status_code == 401:
- return ToolResult.fail("Error: Invalid BOCHA_API_KEY. Please check your API key.")
- if response.status_code == 403:
- return ToolResult.fail("Error: Bocha API - insufficient balance. Please top up at https://open.bocha.cn")
- if response.status_code == 429:
- return ToolResult.fail("Error: Bocha API rate limit reached. Please try again later.")
- if response.status_code != 200:
- return ToolResult.fail(f"Error: Bocha API returned HTTP {response.status_code}")
-
- data = response.json()
-
- # Check API-level error code
+ data = resp.json()
api_code = data.get("code")
if api_code is not None and api_code != 200:
msg = data.get("msg") or "Unknown error"
- return ToolResult.fail(f"Error: Bocha API error (code={api_code}): {msg}")
-
- # Extract and format results
- return self._format_bocha_results(data, query)
-
- def _format_bocha_results(self, data: dict, query: str) -> ToolResult:
- """
- Format Bocha API response into unified result structure
-
- :param data: Raw API response
- :param query: Original query
- :return: Formatted ToolResult
- """
- search_data = data.get("data", {})
- web_pages = search_data.get("webPages", {})
- pages = web_pages.get("value", [])
-
- if not pages:
- return ToolResult.success({
- "query": query,
- "backend": "bocha",
- "total": 0,
- "results": [],
- "message": "No results found"
- })
+ return ToolResult.fail(f"Error: bocha API error (code={api_code}): {msg}")
+ pages = (data.get("data") or {}).get("webPages", {}).get("value", []) or []
results = []
- for page in pages:
- result = {
- "title": page.get("name", ""),
- "url": page.get("url", ""),
- "snippet": page.get("snippet", ""),
- "siteName": page.get("siteName", ""),
- "datePublished": page.get("datePublished") or page.get("dateLastCrawled", ""),
+ for p in pages:
+ item = {
+ "title": p.get("name", ""),
+ "url": p.get("url", ""),
+ "snippet": p.get("snippet", ""),
+ "siteName": p.get("siteName", ""),
+ "datePublished": p.get("datePublished") or p.get("dateLastCrawled", ""),
}
- # Include summary only if present
- if page.get("summary"):
- result["summary"] = page["summary"]
- results.append(result)
-
- total = web_pages.get("totalEstimatedMatches", len(results))
-
+ if p.get("summary"):
+ item["summary"] = p["summary"]
+ results.append(item)
+ total = (data.get("data") or {}).get("webPages", {}).get("totalEstimatedMatches", len(results))
return ToolResult.success({
- "query": query,
- "backend": "bocha",
- "total": total,
- "count": len(results),
- "results": results
+ "query": query, "backend": "bocha",
+ "total": total, "count": len(results), "results": results,
})
- def _search_linkai(self, query: str, count: int, freshness: str) -> ToolResult:
- """
- Search using LinkAI plugin API
+ # ------------------------------------------------------------------
+ # Zhipu
+ # ------------------------------------------------------------------
- :param query: Search query
- :param count: Number of results
- :param freshness: Time range filter
- :return: Formatted search results
- """
- api_key = os.environ.get("LINKAI_API_KEY", "")
- api_base = conf().get("linkai_api_base", "https://api.link-ai.tech")
- url = f"{api_base.rstrip('/')}/v1/plugin/execute"
+ def _search_zhipu(self, query: str, count: int, freshness: str) -> ToolResult:
+ api_key = _get_api_key("zhipu")
+ api_base = (conf().get("zhipu_ai_api_base") or "https://open.bigmodel.cn/api/paas/v4").rstrip("/")
+ url = f"{api_base}/web_search"
+ headers = {
+ "Authorization": f"Bearer {api_key}",
+ "Content-Type": "application/json",
+ }
+
+ # Zhipu Web Search expects `search_query` <= 70 chars; truncate
+ # gracefully so a long agent-supplied query doesn't get rejected.
+ trimmed_query = (query or "")[:70]
+ engine = (_tools_web_search_conf().get("zhipu_search_engine") or "search_pro").strip().lower()
+ if engine not in ("search_std", "search_pro", "search_pro_sogou", "search_pro_quark"):
+ engine = "search_pro"
+
+ payload: Dict[str, Any] = {
+ "search_engine": engine,
+ "search_query": trimmed_query,
+ "search_intent": False,
+ "count": max(1, min(int(count or 10), 50)),
+ "search_recency_filter": freshness if freshness in (
+ "oneDay", "oneWeek", "oneMonth", "oneYear", "noLimit"
+ ) else "noLimit",
+ }
+ content_size = (_tools_web_search_conf().get("zhipu_content_size") or "").strip().lower()
+ if content_size in ("medium", "high"):
+ payload["content_size"] = content_size
+
+ logger.debug(f"[WebSearch] zhipu: query='{trimmed_query}', count={payload['count']}, engine={engine}")
+ resp = requests.post(url, headers=headers, json=payload, timeout=DEFAULT_TIMEOUT)
+
+ if resp.status_code == 401:
+ return ToolResult.fail("Error: Invalid Zhipu API key.")
+ if resp.status_code != 200:
+ return ToolResult.fail(f"Error: Zhipu API returned HTTP {resp.status_code}: {resp.text[:200]}")
+
+ data = resp.json()
+ # Business-level errors (1701/1702/1703 etc.) come back as
+ # {"error": {"code","message"}} even on HTTP 200.
+ if isinstance(data, dict) and data.get("error"):
+ err = data["error"] or {}
+ return ToolResult.fail(f"Error: Zhipu returned {err.get('code')}: {err.get('message','')}")
+
+ items = data.get("search_result") or (data.get("data") or {}).get("search_result") or []
+ results = []
+ for it in items:
+ results.append({
+ "title": it.get("title", ""),
+ "url": it.get("link") or it.get("url", ""),
+ "snippet": it.get("content") or it.get("snippet", ""),
+ "siteName": it.get("media") or it.get("siteName", ""),
+ "datePublished": it.get("publish_date") or it.get("datePublished", ""),
+ })
+ return ToolResult.success({
+ "query": query, "backend": "zhipu",
+ "total": len(results), "count": len(results), "results": results,
+ })
+
+ # ------------------------------------------------------------------
+ # Qianfan (Baidu)
+ # ------------------------------------------------------------------
+
+ def _search_qianfan(self, query: str, count: int, freshness: str) -> ToolResult:
+ api_key = _get_api_key("qianfan")
+ api_base = (conf().get("qianfan_api_base") or "https://qianfan.baidubce.com/v2").rstrip("/")
+ url = f"{api_base}/ai_search/web_search"
+ headers = {
+ "Authorization": f"Bearer {api_key}",
+ "Content-Type": "application/json",
+ "X-Appbuilder-From": "cow",
+ }
+
+ count = max(1, min(int(count or 10), 50))
+ payload: Dict[str, Any] = {
+ "messages": [{"role": "user", "content": query}],
+ "search_source": "baidu_search_v2",
+ "resource_type_filter": [{"type": "web", "top_k": count}],
+ }
+
+ # Baidu AI Search expects freshness as a date-range filter, not a
+ # named recency token. Translate our shared vocabulary into the
+ # underlying page_time range expected by the API.
+ search_filter = self._qianfan_build_freshness_filter(freshness)
+ if search_filter:
+ payload["search_filter"] = search_filter
+
+ logger.debug(f"[WebSearch] qianfan: query='{query}', count={count}, freshness={freshness!r}")
+ resp = requests.post(url, headers=headers, json=payload, timeout=DEFAULT_TIMEOUT)
+
+ if resp.status_code == 401:
+ return ToolResult.fail("Error: Invalid Qianfan API key.")
+ if resp.status_code != 200:
+ return ToolResult.fail(f"Error: Qianfan API returned HTTP {resp.status_code}: {resp.text[:200]}")
+
+ data = resp.json()
+ # Even on HTTP 200 Baidu surfaces business errors as {"code","message"}.
+ if isinstance(data, dict) and data.get("code"):
+ return ToolResult.fail(f"Error: Qianfan returned {data.get('code')}: {data.get('message','')}")
+
+ refs = data.get("references") or []
+ results = []
+ for d in refs:
+ results.append({
+ "title": d.get("title", ""),
+ "url": d.get("url", ""),
+ "snippet": (d.get("content") or "")[:200],
+ "siteName": d.get("web_anchor") or d.get("website") or "",
+ "datePublished": d.get("date", ""),
+ })
+ return ToolResult.success({
+ "query": query, "backend": "qianfan",
+ "total": len(results), "count": len(results), "results": results,
+ })
+
+ @staticmethod
+ def _qianfan_build_freshness_filter(freshness: str) -> Optional[Dict[str, Any]]:
+ if not freshness or freshness == "noLimit":
+ return None
+ delta_days = {"oneDay": 1, "oneWeek": 7, "oneMonth": 30, "oneYear": 365}.get(freshness)
+ if not delta_days:
+ return None
+ from datetime import datetime, timedelta
+ now = datetime.now()
+ end_date = (now + timedelta(days=1)).strftime("%Y-%m-%d")
+ start_date = (now - timedelta(days=delta_days)).strftime("%Y-%m-%d")
+ return {"range": {"page_time": {"gte": start_date, "lt": end_date}}}
+
+ # ------------------------------------------------------------------
+ # LinkAI (plugin)
+ # ------------------------------------------------------------------
+
+ def _search_linkai(self, query: str, count: int, freshness: str) -> ToolResult:
+ api_key = _get_api_key("linkai")
+ api_base = (conf().get("linkai_api_base") or "https://api.link-ai.tech").rstrip("/")
+ url = f"{api_base}/v1/plugin/execute"
from common.utils import get_cloud_headers
headers = get_cloud_headers(api_key)
- payload = {
- "code": "web-search",
- "args": {
- "query": query,
- "count": count,
- "freshness": freshness
- }
- }
+ payload = {"code": "web-search", "args": {"query": query, "count": count, "freshness": freshness}}
+ logger.debug(f"[WebSearch] linkai: query='{query}', count={count}")
+ resp = requests.post(url, headers=headers, json=payload, timeout=DEFAULT_TIMEOUT)
- logger.debug(f"[WebSearch] LinkAI search: query='{query}', count={count}")
-
- response = requests.post(url, headers=headers, json=payload, timeout=DEFAULT_TIMEOUT)
-
- if response.status_code == 401:
- return ToolResult.fail("Error: Invalid LINKAI_API_KEY. Please check your API key.")
- if response.status_code != 200:
- return ToolResult.fail(f"Error: LinkAI API returned HTTP {response.status_code}")
-
- data = response.json()
+ if resp.status_code == 401:
+ return ToolResult.fail("Error: Invalid LinkAI API key.")
+ if resp.status_code != 200:
+ return ToolResult.fail(f"Error: LinkAI API returned HTTP {resp.status_code}")
+ data = resp.json()
if not data.get("success"):
msg = data.get("message") or "Unknown error"
return ToolResult.fail(f"Error: LinkAI search failed: {msg}")
- return self._format_linkai_results(data, query)
-
- def _format_linkai_results(self, data: dict, query: str) -> ToolResult:
- """
- Format LinkAI API response into unified result structure.
- LinkAI returns the search data in data.data field, which follows
- the same Bing-compatible format as Bocha.
-
- :param data: Raw API response
- :param query: Original query
- :return: Formatted ToolResult
- """
- raw_data = data.get("data", "")
-
- # LinkAI may return data as a JSON string
- if isinstance(raw_data, str):
+ raw = data.get("data", "")
+ if isinstance(raw, str):
try:
- raw_data = json.loads(raw_data)
+ raw = json.loads(raw)
except (json.JSONDecodeError, TypeError):
- # If data is plain text, return it as a single result
return ToolResult.success({
- "query": query,
- "backend": "linkai",
- "total": 1,
- "count": 1,
- "results": [{"content": raw_data}]
+ "query": query, "backend": "linkai",
+ "total": 1, "count": 1, "results": [{"content": raw}],
})
- # If the response follows Bing-compatible structure
- if isinstance(raw_data, dict):
- web_pages = raw_data.get("webPages", {})
- pages = web_pages.get("value", [])
-
+ if isinstance(raw, dict):
+ pages = (raw.get("webPages") or {}).get("value", []) or []
if pages:
results = []
- for page in pages:
- result = {
- "title": page.get("name", ""),
- "url": page.get("url", ""),
- "snippet": page.get("snippet", ""),
- "siteName": page.get("siteName", ""),
- "datePublished": page.get("datePublished") or page.get("dateLastCrawled", ""),
+ for p in pages:
+ item = {
+ "title": p.get("name", ""),
+ "url": p.get("url", ""),
+ "snippet": p.get("snippet", ""),
+ "siteName": p.get("siteName", ""),
+ "datePublished": p.get("datePublished") or p.get("dateLastCrawled", ""),
}
- if page.get("summary"):
- result["summary"] = page["summary"]
- results.append(result)
-
- total = web_pages.get("totalEstimatedMatches", len(results))
+ if p.get("summary"):
+ item["summary"] = p["summary"]
+ results.append(item)
+ total = (raw.get("webPages") or {}).get("totalEstimatedMatches", len(results))
return ToolResult.success({
- "query": query,
- "backend": "linkai",
- "total": total,
- "count": len(results),
- "results": results
+ "query": query, "backend": "linkai",
+ "total": total, "count": len(results), "results": results,
})
- # Fallback: return raw data
return ToolResult.success({
- "query": query,
- "backend": "linkai",
- "total": 1,
- "count": 1,
- "results": [{"content": str(raw_data)}]
+ "query": query, "backend": "linkai",
+ "total": 1, "count": 1, "results": [{"content": str(raw)}],
})
diff --git a/app.py b/app.py
index ba2ab265..dbb15209 100644
--- a/app.py
+++ b/app.py
@@ -289,6 +289,16 @@ def _warmup_mcp_tools():
logger.warning(f"[App] MCP warmup failed (non-fatal): {e}")
+def _warmup_scheduler():
+ """Eager-init AgentBridge so the scheduler thread starts at process
+ boot rather than waiting for the first user message."""
+ try:
+ from bridge.bridge import Bridge
+ Bridge().get_agent_bridge()
+ except Exception as e:
+ logger.warning(f"[App] Scheduler warmup failed: {e}")
+
+
def _sync_builtin_skills():
"""Sync builtin skills from project skills/ to workspace skills/ on startup."""
import shutil
@@ -354,6 +364,8 @@ def run():
# latency isn't dominated by npx package downloads.
_warmup_mcp_tools()
+ _warmup_scheduler()
+
logger.info(f"[App] Starting channels: {channel_names}")
_channel_mgr = ChannelManager()
diff --git a/bridge/agent_bridge.py b/bridge/agent_bridge.py
index e60ffd9d..a924dab2 100644
--- a/bridge/agent_bridge.py
+++ b/bridge/agent_bridge.py
@@ -5,7 +5,7 @@ Agent Bridge - Integrates Agent system with existing COW bridge
import os
from typing import Optional, List
-from agent.protocol import Agent, LLMModel, LLMRequest
+from agent.protocol import Agent, LLMModel, LLMRequest, get_cancel_registry
from bridge.agent_event_handler import AgentEventHandler
from bridge.agent_initializer import AgentInitializer
from bridge.bridge import Bridge
@@ -285,6 +285,15 @@ class AgentBridge:
# Create helper instances
self.initializer = AgentInitializer(bridge, self)
+
+ # Eager-start the scheduler so cron tasks fire without waiting
+ # for the first user message. init_scheduler is idempotent.
+ try:
+ from agent.tools.scheduler.integration import init_scheduler
+ if init_scheduler(self):
+ self.scheduler_initialized = True
+ except Exception as e:
+ logger.warning(f"[AgentBridge] Eager scheduler init failed: {e}")
def create_agent(self, system_prompt: str, tools: List = None, **kwargs) -> Agent:
"""
Create the super agent with COW integration
@@ -390,11 +399,22 @@ class AgentBridge:
"""
session_id = None
agent = None
+ request_id = None
+ cancel_event = None
try:
# Extract session_id from context for user isolation
if context:
session_id = context.kwargs.get("session_id") or context.get("session_id")
-
+ request_id = context.kwargs.get("request_id") or context.get("request_id")
+
+ # Register a cancel token. Prefer per-turn request_id (web),
+ # fall back to session_id (IM channels). The Event is polled by
+ # AgentStreamExecutor at safe checkpoints.
+ registry = get_cancel_registry()
+ token_key = request_id or session_id
+ if token_key:
+ cancel_event = registry.register(token_key, session_id=session_id)
+
# Get agent for this session (will auto-initialize if needed)
agent = self.get_agent(session_id=session_id)
if not agent:
@@ -449,7 +469,8 @@ class AgentBridge:
response = agent.run_stream(
user_message=query,
on_event=event_handler.handle_event,
- clear_history=clear_history
+ clear_history=clear_history,
+ cancel_event=cancel_event,
)
finally:
# Restore original tools
@@ -459,6 +480,13 @@ class AgentBridge:
# Log execution summary
event_handler.log_summary()
+ # Release cancel token; keep registry bounded.
+ if token_key:
+ try:
+ registry.unregister(token_key)
+ except Exception:
+ pass
+
# Persist new messages generated during this run
if session_id:
channel_type = (context.get("channel_type") or "") if context else ""
@@ -512,6 +540,12 @@ class AgentBridge:
logger.info(f"[AgentBridge] Cleared DB for session after error: {session_id}")
except Exception as db_err:
logger.warning(f"[AgentBridge] Failed to clear DB after error: {db_err}")
+ # Release cancel token on error path too (idempotent).
+ if cancel_event is not None and (request_id or session_id):
+ try:
+ get_cancel_registry().unregister(request_id or session_id)
+ except Exception:
+ pass
return Reply(ReplyType.ERROR, f"Agent error: {str(e)}")
def _schedule_mcp_hot_reload(self, agent):
diff --git a/bridge/agent_event_handler.py b/bridge/agent_event_handler.py
index 50826235..35173730 100644
--- a/bridge/agent_event_handler.py
+++ b/bridge/agent_event_handler.py
@@ -2,44 +2,40 @@
Agent Event Handler - Handles agent events and thinking process output
"""
+from common import const
from common.log import logger
+# Cap intermediate thinking messages on weixin to stay within send quota.
+WEIXIN_THINKING_INSTANT_MAX = 7
+
class AgentEventHandler:
"""
Handles agent events and optionally sends intermediate messages to channel
"""
-
+
def __init__(self, context=None, original_callback=None):
- """
- Initialize event handler
-
- Args:
- context: COW context (for accessing channel)
- original_callback: Original event callback to chain
- """
self.context = context
self.original_callback = original_callback
-
- # Get channel for sending intermediate messages
+
self.channel = None
if context:
self.channel = context.kwargs.get("channel") if hasattr(context, "kwargs") else None
-
+
self.current_content = ""
self.turn_number = 0
-
+
+ channel_type = ""
+ if context and hasattr(context, "kwargs"):
+ channel_type = context.kwargs.get("channel_type", "") or ""
+ self._is_weixin = channel_type == const.WEIXIN
+ self._thinking_sent_count = 0
+ self._merged_buf: list[str] = []
+
def handle_event(self, event):
- """
- Main event handler
-
- Args:
- event: Event dict with type and data
- """
event_type = event.get("type")
data = event.get("data", {})
-
- # Dispatch to specific handlers
+
if event_type == "turn_start":
self._handle_turn_start(data)
elif event_type == "message_update":
@@ -52,25 +48,23 @@ class AgentEventHandler:
self._handle_tool_execution_start(data)
elif event_type == "tool_execution_end":
self._handle_tool_execution_end(data)
-
- # Call original callback if provided
+ elif event_type == "agent_end":
+ self._handle_agent_end(data)
+
if self.original_callback:
self.original_callback(event)
-
+
def _handle_turn_start(self, data):
- """Handle turn start event"""
self.turn_number = data.get("turn", 0)
self.current_content = ""
-
+
def _handle_message_update(self, data):
- """Handle message update event (streaming content text)"""
delta = data.get("delta", "")
self.current_content += delta
-
+
def _handle_message_end(self, data):
- """Handle message end event"""
tool_calls = data.get("tool_calls", [])
-
+
if tool_calls:
if self.current_content.strip():
logger.info(f"💭 {self.current_content.strip()[:200]}{'...' if len(self.current_content) > 200 else ''}")
@@ -78,35 +72,54 @@ class AgentEventHandler:
else:
if self.current_content.strip():
logger.debug(f"💬 {self.current_content.strip()[:200]}{'...' if len(self.current_content) > 200 else ''}")
-
+ # Drain weixin buffer before final reply leaves chat_channel
+ self._flush_merged_now()
+
self.current_content = ""
-
+
+ def _handle_agent_end(self, data):
+ self._flush_merged_now()
+
def _handle_tool_execution_start(self, data):
- """Handle tool execution start event - logged by agent_stream.py"""
pass
-
+
def _handle_tool_execution_end(self, data):
- """Handle tool execution end event - logged by agent_stream.py"""
pass
-
+
def _send_to_channel(self, message):
- """
- Try to send intermediate message to channel.
- Skipped in SSE mode because thinking text is already streamed via on_event.
- """
if self.context and self.context.get("on_event"):
return
+ if not self.channel:
+ return
+
+ if not self._is_weixin:
+ self._do_send(message)
+ return
+
+ if self._thinking_sent_count < WEIXIN_THINKING_INSTANT_MAX:
+ self._do_send(message)
+ self._thinking_sent_count += 1
+ return
+
+ self._merged_buf.append(message)
+
+ def _flush_merged_now(self):
+ if not self._merged_buf:
+ return
+ merged = "\n\n".join(self._merged_buf)
+ count = len(self._merged_buf)
+ self._merged_buf = []
+ logger.debug(f"[AgentEventHandler] Flushing {count} merged thinking msgs, len={len(merged)}")
+ self._do_send(merged)
+ self._thinking_sent_count += 1
+
+ def _do_send(self, message):
+ try:
+ from bridge.reply import Reply, ReplyType
+ reply = Reply(ReplyType.TEXT, message)
+ self.channel._send(reply, self.context)
+ except Exception as e:
+ logger.debug(f"[AgentEventHandler] Failed to send to channel: {e}")
- if self.channel:
- try:
- from bridge.reply import Reply, ReplyType
- reply = Reply(ReplyType.TEXT, message)
- self.channel._send(reply, self.context)
- except Exception as e:
- logger.debug(f"[AgentEventHandler] Failed to send to channel: {e}")
-
def log_summary(self):
- """Log execution summary - simplified"""
- # Summary removed as per user request
- # Real-time logging during execution is sufficient
pass
diff --git a/bridge/agent_initializer.py b/bridge/agent_initializer.py
index d17dcb0c..7d5afb4a 100644
--- a/bridge/agent_initializer.py
+++ b/bridge/agent_initializer.py
@@ -521,7 +521,7 @@ class AgentInitializer:
if tool_name == "web_search":
from agent.tools.web_search.web_search import WebSearch
if not WebSearch.is_available():
- logger.debug("[AgentInitializer] WebSearch skipped - no BOCHA_API_KEY or LINKAI_API_KEY")
+ logger.debug("[AgentInitializer] WebSearch skipped - no search provider configured")
continue
# Special handling for EnvConfig tool
diff --git a/bridge/bridge.py b/bridge/bridge.py
index 753e394a..6eeb0887 100644
--- a/bridge/bridge.py
+++ b/bridge/bridge.py
@@ -14,7 +14,9 @@ class Bridge(object):
def __init__(self):
self.btype = {
"chat": const.OPENAI,
- "voice_to_text": conf().get("voice_to_text", "openai"),
+ # Empty `voice_to_text` (the default in new configs) triggers
+ # the auto-pick below — see _auto_pick_voice_to_text for order.
+ "voice_to_text": conf().get("voice_to_text") or self._auto_pick_voice_to_text(),
"text_to_voice": conf().get("text_to_voice", "google"),
"translate": conf().get("translate", "baidu"),
}
@@ -61,6 +63,10 @@ class Bridge(object):
if model_type and model_type.startswith("deepseek"):
self.btype["chat"] = const.DEEPSEEK
+ # 小米 MiMo 系列模型，全部以 mimo- 开头
+ if model_type and model_type.startswith("mimo-"):
+ self.btype["chat"] = const.MIMO
+
if model_type and isinstance(model_type, str):
lowered_model_type = model_type.lower()
if lowered_model_type == const.QIANFAN or lowered_model_type.startswith("ernie"):
@@ -84,6 +90,46 @@ class Bridge(object):
self.chat_bots = {}
self._agent_bridge = None
+ def refresh_voice(self):
+ """Re-read voice_to_text / text_to_voice from config and drop the
+ cached voice bots so the next call picks up the new provider.
+ Used by the web console after the user edits voice settings.
+ Does NOT touch the agent_bridge / agent state.
+ """
+ new_v2t = conf().get("voice_to_text") or self._auto_pick_voice_to_text()
+ new_t2v = conf().get("text_to_voice", "google")
+ if conf().get("use_linkai") and conf().get("linkai_api_key"):
+ if not conf().get("voice_to_text") or conf().get("voice_to_text") in ["openai"]:
+ new_v2t = const.LINKAI
+ if not conf().get("text_to_voice") or conf().get("text_to_voice") in ["openai", const.TTS_1, const.TTS_1_HD]:
+ new_t2v = const.LINKAI
+ self.btype["voice_to_text"] = new_v2t
+ self.btype["text_to_voice"] = new_t2v
+ self.bots.pop("voice_to_text", None)
+ self.bots.pop("text_to_voice", None)
+ logger.info(f"[Bridge] voice refreshed: voice_to_text={new_v2t}, text_to_voice={new_t2v}")
+
+ @staticmethod
+ def _auto_pick_voice_to_text() -> str:
+ """Pick an ASR provider by configured api keys when voice_to_text is
+ unset. Order matches the web console: openai → dashscope → zhipu →
+ linkai. Falls back to 'openai' when nothing is configured so the
+ original "missing key" error is preserved.
+ """
+ def has(k: str) -> bool:
+ v = (conf().get(k) or "").strip()
+ return v != "" and v not in ("YOUR API KEY", "YOUR_API_KEY")
+
+ for key, provider in (
+ ("open_ai_api_key", "openai"),
+ ("dashscope_api_key", "dashscope"),
+ ("zhipu_ai_api_key", "zhipu"),
+ ("linkai_api_key", "linkai"),
+ ):
+ if has(key):
+ return provider
+ return "openai"
+
# 模型对应的接口
def get_bot(self, typename):
if self.bots.get(typename) is None:
diff --git a/channel/channel_factory.py b/channel/channel_factory.py
index 10000226..2645945e 100644
--- a/channel/channel_factory.py
+++ b/channel/channel_factory.py
@@ -42,6 +42,12 @@ def create_channel(channel_type) -> Channel:
elif channel_type == const.QQ:
from channel.qq.qq_channel import QQChannel
ch = QQChannel()
+ elif channel_type == const.TELEGRAM:
+ from channel.telegram.telegram_channel import TelegramChannel
+ ch = TelegramChannel()
+ elif channel_type == const.SLACK:
+ from channel.slack.slack_channel import SlackChannel
+ ch = SlackChannel()
elif channel_type in (const.WEIXIN, "wx"):
from channel.weixin.weixin_channel import WeixinChannel
ch = WeixinChannel()
diff --git a/channel/chat_channel.py b/channel/chat_channel.py
index 3251c286..6a9a1952 100644
--- a/channel/chat_channel.py
+++ b/channel/chat_channel.py
@@ -171,7 +171,13 @@ class ChatChannel(Channel):
if "desire_rtype" not in context and conf().get("always_reply_voice") and ReplyType.VOICE not in self.NOT_SUPPORT_REPLYTYPE:
context["desire_rtype"] = ReplyType.VOICE
elif context.type == ContextType.VOICE:
- if "desire_rtype" not in context and conf().get("voice_reply_voice") and ReplyType.VOICE not in self.NOT_SUPPORT_REPLYTYPE:
+ # Voice input replies with voice when either voice_reply_voice
+ # (mirror voice) or the global always_reply_voice toggle is on.
+ if (
+ "desire_rtype" not in context
+ and (conf().get("voice_reply_voice") or conf().get("always_reply_voice"))
+ and ReplyType.VOICE not in self.NOT_SUPPORT_REPLYTYPE
+ ):
context["desire_rtype"] = ReplyType.VOICE
return context
@@ -264,6 +270,8 @@ class ChatChannel(Channel):
if reply.type == ReplyType.TEXT:
reply_text = reply.content
if desire_rtype == ReplyType.VOICE and ReplyType.VOICE not in self.NOT_SUPPORT_REPLYTYPE:
+ # Preserve original text for the "text-then-voice" pattern in _send_reply.
+ context["voice_reply_text"] = reply.content
reply = super().build_text_to_voice(reply.content)
return self._decorate_reply(context, reply)
if context.get("isgroup", False):
@@ -311,6 +319,15 @@ class ChatChannel(Channel):
# 短暂延迟后发送图片
time.sleep(0.3)
self._send(reply, context)
+ # Send text bubble before voice, unless channel already streamed
+ # the text (feishu) or natively renders STT under the voice (wechatcom).
+ elif reply.type == ReplyType.VOICE and context.get("voice_reply_text") \
+ and not context.get("feishu_streamed") \
+ and context.get("channel_type") not in ("wechatcom_app",):
+ text_reply = Reply(ReplyType.TEXT, context.get("voice_reply_text"))
+ self._send(text_reply, context)
+ time.sleep(0.3)
+ self._send(reply, context)
else:
self._send(reply, context)
@@ -421,8 +438,21 @@ class ChatChannel(Channel):
return func
+ # Chat commands that must bypass the per-session serial queue,
+ # otherwise /cancel would queue behind the task it tries to cancel.
+ # Use /cancel (not /stop) to avoid colliding with `cow stop` CLI.
+ _BYPASS_QUEUE_COMMANDS = ("/cancel",)
+
def produce(self, context: Context):
session_id = context["session_id"]
+
+ # Fast path: /cancel must not enter the queue.
+ if context.type == ContextType.TEXT and context.content:
+ stripped = context.content.strip().lower()
+ if stripped in self._BYPASS_QUEUE_COMMANDS:
+ self._handle_cancel_command(context, session_id)
+ return
+
with self.lock:
if session_id not in self.sessions:
self.sessions[session_id] = [
@@ -434,6 +464,29 @@ class ChatChannel(Channel):
else:
self.sessions[session_id][0].put(context)
+ def _handle_cancel_command(self, context: Context, session_id: str) -> None:
+ """Cancel any in-flight agent run for *session_id* and reply inline.
+
+ Runs synchronously on the caller's thread. Reply is sent through
+ _send_reply so plugins (e.g. logging) still observe it.
+ """
+ try:
+ from agent.protocol import get_cancel_registry
+ from bridge.reply import Reply, ReplyType
+
+ cancelled = get_cancel_registry().cancel_session(session_id)
+ text = (
+ "🛑 已中止"
+ if cancelled > 0
+ else "当前没有可中止的任务。"
+ )
+ logger.info(
+ f"[chat_channel] /cancel fast-path: session={session_id}, cancelled={cancelled}"
+ )
+ self._send_reply(context, Reply(ReplyType.TEXT, text))
+ except Exception as e:
+ logger.warning(f"[chat_channel] /cancel fast-path failed: {e}")
+
# 消费者函数，单独线程，用于从消息队列中取出消息并处理
def consume(self):
while True:
diff --git a/channel/dingtalk/dingtalk_channel.py b/channel/dingtalk/dingtalk_channel.py
index d572e35d..b1ae86c2 100644
--- a/channel/dingtalk/dingtalk_channel.py
+++ b/channel/dingtalk/dingtalk_channel.py
@@ -86,6 +86,8 @@ def _check(func):
@singleton
class DingTalkChanel(ChatChannel, dingtalk_stream.ChatbotHandler):
+ NOT_SUPPORT_REPLYTYPE = []
+
dingtalk_client_id = conf().get('dingtalk_client_id')
dingtalk_client_secret = conf().get('dingtalk_client_secret')
@@ -870,6 +872,48 @@ class DingTalkChanel(ChatChannel, dingtalk_stream.ChatbotHandler):
self.reply_text("抱歉，文件上传失败", incoming_message)
return
+ # Native sampleAudio. Upload only accepts ogg/amr, so convert TTS mp3/wav to amr.
+ elif reply.type == ReplyType.VOICE:
+ logger.info(f"[DingTalk] Sending voice: {reply.content}")
+ access_token = self.get_access_token()
+ if not access_token:
+ logger.error("[DingTalk] Cannot get access token for voice")
+ self.reply_text("抱歉，语音发送失败（无法获取token）", incoming_message)
+ return
+
+ voice_path = reply.content
+ if voice_path.startswith("file://"):
+ voice_path = voice_path[7:]
+
+ amr_path = voice_path
+ duration_ms = 0
+ if not voice_path.lower().endswith((".amr", ".ogg")):
+ try:
+ from voice.audio_convert import any_to_amr
+ amr_path = os.path.splitext(voice_path)[0] + ".amr"
+ duration_ms = int(any_to_amr(voice_path, amr_path) or 0)
+ except Exception as e:
+ logger.error(f"[DingTalk] Failed to convert voice to amr: {e}")
+ self.reply_text("抱歉，语音转码失败", incoming_message)
+ return
+
+ media_id = self.upload_media(amr_path, media_type="voice")
+ if not media_id:
+ logger.error("[DingTalk] Failed to upload voice media")
+ self.reply_text("抱歉，语音上传失败", incoming_message)
+ return
+
+ msg_param = {
+ "mediaId": media_id,
+ "duration": str(duration_ms or 1000),
+ }
+ success = self._send_file_message(
+ access_token, incoming_message, "sampleAudio", msg_param, isgroup
+ )
+ if not success:
+ self.reply_text("抱歉，语音发送失败", incoming_message)
+ return
+
# 处理文本消息
elif reply.type == ReplyType.TEXT:
logger.info(f"[DingTalk] Sending text message, length={len(reply.content)}")
diff --git a/channel/feishu/feishu_channel.py b/channel/feishu/feishu_channel.py
index f479394a..9a9f3307 100644
--- a/channel/feishu/feishu_channel.py
+++ b/channel/feishu/feishu_channel.py
@@ -752,6 +752,9 @@ class FeiShuChanel(ChatChannel):
init_in_flight = [False]
# 一旦初始化失败就长期标记为 disabled，本次回复不再尝试任何流式调用
disabled = [False]
+ # True after agent_cancelled: agent_end stops rewriting the card
+ # with stale final_response and just finalizes current content.
+ cancelled = [False]
lock = threading.Lock()
# ---- 异步推送队列 ----------------------------------------------------
@@ -1076,18 +1079,42 @@ class FeiShuChanel(ChatChannel):
message_id[0] = None
sequence[0] = 0
+ elif event_type == "agent_cancelled":
+ # Lock channel into "no-rewrite" mode: the subsequent
+ # agent_end's final_response is from the last *completed*
+ # turn (the user already saw it), so rewriting the card
+ # would duplicate it visually.
+ with lock:
+ cancelled[0] = True
+
elif event_type == "agent_end":
# 最终回复：用 final_response 覆盖当前流式卡片，然后关闭流式模式。
final_response = data.get("final_response", "")
- if not final_response:
- return
- final_text = str(final_response)
# 标记 streamed 让 chat_channel 跳过 send()
context["feishu_streamed"] = True
with lock:
+ was_cancelled = cancelled[0]
has_card = card_id[0] is not None
init_busy = init_in_flight[0]
+ pending_text = current_text[0]
+
+ if was_cancelled:
+ # Cancelled path: finalize the in-flight card with
+ # partial output (or a short marker if empty); drop
+ # stale final_response to avoid duplicating last turn.
+ if has_card:
+ _drain_push_queue()
+ partial = (pending_text or "").rstrip()
+ final_text = partial or "_(已中止)_"
+ _stream_update_text(final_text)
+ _close_streaming_mode(final_text)
+ push_queue.put(None)
+ return
+
+ if not final_response:
+ return
+ final_text = str(final_response)
# 罕见情况：agent_end 触发时还没创建过卡片（极快返回 / 没有
# message_update），主动创建一张承载 final_text。
@@ -1515,10 +1542,16 @@ class FeiShuChanel(ChatChannel):
else:
context.type = ContextType.TEXT
context.content = content.strip()
+ # Text input opts into voice replies only when the always-on toggle is set.
+ if "desire_rtype" not in context and conf().get("always_reply_voice"):
+ context["desire_rtype"] = ReplyType.VOICE
elif context.type == ContextType.VOICE:
- # 2.语音请求
- if "desire_rtype" not in context and conf().get("voice_reply_voice"):
+ # 2.语音请求: voice input replies with voice if either
+ # voice_reply_voice (mirror reply) or always_reply_voice is on.
+ if "desire_rtype" not in context and (
+ conf().get("voice_reply_voice") or conf().get("always_reply_voice")
+ ):
context["desire_rtype"] = ReplyType.VOICE
return context
diff --git a/channel/slack/__init__.py b/channel/slack/__init__.py
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/channel/slack/__init__.py
@@ -0,0 +1 @@
+
diff --git a/channel/slack/slack_channel.py b/channel/slack/slack_channel.py
new file mode 100644
index 00000000..8e82fcc5
--- /dev/null
+++ b/channel/slack/slack_channel.py
@@ -0,0 +1,506 @@
+"""
+Slack channel via Bolt for Python (Socket Mode).
+
+Features:
+- Direct message & channel chat (text / image / file)
+- Channel trigger: @mention or reply in a thread the bot is in (configurable)
+- /cancel fast-path matches Web channel behaviour
+- Socket Mode: no public IP / callback URL required, works behind NAT
+
+Implementation note:
+ slack_bolt's SocketModeHandler is blocking and runs its own background
+ threads. We start it in a dedicated thread so the rest of cow (sync) stays
+ untouched. Inbound events are dispatched onto cow's existing sync
+ ChatChannel.produce() pipeline; outbound send() calls the Slack Web API
+ client directly (it is sync-safe).
+"""
+
+import os
+import re
+import threading
+
+import requests
+
+from bridge.context import Context, ContextType
+from bridge.reply import Reply, ReplyType
+from channel.chat_channel import ChatChannel, check_prefix
+from channel.slack.slack_message import SlackMessage
+from common.expired_dict import ExpiredDict
+from common.log import logger
+from common.singleton import singleton
+from config import conf
+
+
+@singleton
+class SlackChannel(ChatChannel):
+ NOT_SUPPORT_REPLYTYPE = []
+
+ def __init__(self):
+ super().__init__()
+ self.bot_token = ""
+ self.app_token = ""
+ self.bot_user_id = "" # used to strip @mention and ignore self messages
+ self._app = None
+ self._handler = None
+ self._client = None
+ self._loop_thread = None
+ # Idempotent dedup; Slack retries event delivery on slow ack
+ self._received_msgs = ExpiredDict(60 * 60 * 1)
+
+ # Disable group whitelist / prefix checks (we handle triggering ourselves
+ # in _should_reply_in_channel), aligned with telegram / feishu channels.
+ conf()["group_name_white_list"] = ["ALL_GROUP"]
+ conf()["single_chat_prefix"] = [""]
+
+ # ------------------------------------------------------------------
+ # Lifecycle
+ # ------------------------------------------------------------------
+
+ def startup(self):
+ self.bot_token = conf().get("slack_bot_token", "")
+ self.app_token = conf().get("slack_app_token", "")
+ if not self.bot_token or not self.app_token:
+ err = "[Slack] slack_bot_token and slack_app_token are both required"
+ logger.error(err)
+ self.report_startup_error(err)
+ return
+
+ # Guard against the common mistake of swapping the two tokens:
+ # bot token must start with xoxb-, app-level token with xapp-.
+ if not self.bot_token.startswith("xoxb-") or not self.app_token.startswith("xapp-"):
+ err = (
+ "[Slack] token type mismatch: slack_bot_token must start with 'xoxb-' "
+ "and slack_app_token must start with 'xapp-' (they look swapped)"
+ )
+ logger.error(err)
+ self.report_startup_error(err)
+ return
+
+ try:
+ from slack_bolt import App
+ from slack_bolt.adapter.socket_mode import SocketModeHandler
+ except ImportError:
+ err = (
+ "[Slack] slack_bolt is not installed. "
+ "Run: pip install slack_bolt"
+ )
+ logger.error(err)
+ self.report_startup_error(err)
+ return
+
+ try:
+ self._app = App(token=self.bot_token)
+ self._client = self._app.client
+
+ # Resolve our own bot user id (needed for @mention strip / self-ignore)
+ auth = self._client.auth_test()
+ self.bot_user_id = auth.get("user_id", "")
+ self.name = self.bot_user_id # ChatChannel uses self.name to strip @-mention
+ logger.info(f"[Slack] Bot logged in as user_id={self.bot_user_id}, team={auth.get('team')}")
+ except Exception as e:
+ err = f"[Slack] auth_test failed: {e}"
+ logger.error(err)
+ self.report_startup_error(err)
+ return
+
+ self._register_handlers()
+
+ self._handler = SocketModeHandler(self._app, self.app_token)
+
+ def _run():
+ try:
+ logger.info("[Slack] Starting Socket Mode connection...")
+ self.report_startup_success()
+ logger.info("[Slack] ✅ Slack bot ready, listening for events")
+ self._handler.start()
+ except Exception as e:
+ logger.error(f"[Slack] socket mode crashed: {e}", exc_info=True)
+ self.report_startup_error(str(e))
+ finally:
+ logger.info("[Slack] socket mode exited")
+
+ self._loop_thread = threading.Thread(target=_run, daemon=True, name="slack-socket")
+ self._loop_thread.start()
+ # Block startup() until the handler thread exits, matching other channels'
+ # behaviour (startup is a blocking call).
+ self._loop_thread.join()
+
+ def _register_handlers(self):
+ app = self._app
+
+ # app_mention: bot is @-mentioned in a channel
+ @app.event("app_mention")
+ def _on_app_mention(event, ack):
+ ack()
+ self._handle_event(event, is_group=True)
+
+ # message: DMs and channel messages (including thread replies)
+ @app.event("message")
+ def _on_message(event, ack):
+ ack()
+ self._handle_message_event(event)
+
+ def stop(self):
+ logger.info("[Slack] stop() called")
+ try:
+ if self._handler is not None:
+ self._handler.close()
+ except Exception as e:
+ logger.warning(f"[Slack] handler close error: {e}")
+ if self._loop_thread and self._loop_thread.is_alive():
+ try:
+ self._loop_thread.join(timeout=10)
+ except Exception:
+ pass
+ logger.info("[Slack] stop() completed")
+
+ # ------------------------------------------------------------------
+ # Inbound: slack event -> ChatMessage -> ChatChannel.produce
+ # ------------------------------------------------------------------
+
+ def _handle_message_event(self, event: dict):
+ """Route a raw `message` event: skip bot/system noise, decide grouping."""
+ try:
+ logger.debug(
+ f"[Slack] message event: channel_type={event.get('channel_type')}, "
+ f"subtype={event.get('subtype')}, user={event.get('user')}, "
+ f"ts={event.get('ts')}, thread_ts={event.get('thread_ts')}"
+ )
+ # Ignore bot messages (including our own) and message edits/deletes
+ if event.get("bot_id") or event.get("subtype") in ("bot_message", "message_changed", "message_deleted"):
+ return
+ if event.get("user") == self.bot_user_id:
+ return
+
+ channel_type = event.get("channel_type", "")
+ # DM (im) is single chat; channel/group is group chat. app_mention
+ # already covers channel @-mentions, so for plain channel messages we
+ # only react when configured / thread-following.
+ is_group = channel_type in ("channel", "group", "mpim")
+ if is_group:
+ # app_mention handler covers explicit @bot; here we only handle
+ # follow-up replies in threads the bot participates in.
+ if not self._should_reply_in_channel(event):
+ return
+ self._handle_event(event, is_group=is_group)
+ except Exception as e:
+ logger.error(f"[Slack] _handle_message_event error: {e}", exc_info=True)
+
+ def _handle_event(self, event: dict, is_group: bool):
+ """Parse event -> build SlackMessage -> produce()."""
+ try:
+ channel_id = event.get("channel", "")
+ ts = event.get("ts", "")
+ if not channel_id:
+ return
+
+ # Idempotent dedup
+ msg_uid = f"{channel_id}:{ts}"
+ if self._received_msgs.get(msg_uid):
+ return
+ self._received_msgs[msg_uid] = True
+
+ # Parse type + download media if needed.
+ ctype, content, caption = self._parse_event(event)
+ if ctype is None:
+ logger.debug(f"[Slack] unsupported message type, skip. event={event}")
+ return
+
+ # Strip <@bot_user_id> mention from channel text
+ if is_group and self.bot_user_id:
+ if ctype == ContextType.TEXT and content:
+ content = self._strip_at_mention(content)
+ if caption:
+ caption = self._strip_at_mention(caption)
+
+ slack_msg = SlackMessage(
+ event,
+ is_group=is_group,
+ bot_user_id=self.bot_user_id,
+ ctype=ctype,
+ content=content,
+ )
+ slack_msg.is_at = is_group # if we reached here in a channel, bot is mentioned/threaded
+
+ from channel.file_cache import get_file_cache
+ file_cache = get_file_cache()
+ session_id = self._compute_session_id(event, is_group)
+
+ # Media + caption together: treat as a complete query and bypass the cache
+ if ctype in (ContextType.IMAGE, ContextType.FILE) and caption:
+ tag = "image" if ctype == ContextType.IMAGE else "file"
+ merged_text = f"{caption}\n[{tag}: {content}]"
+ slack_msg.ctype = ContextType.TEXT
+ slack_msg.content = merged_text
+ ctype = ContextType.TEXT
+ logger.info(f"[Slack] Media+caption merged for session {session_id}")
+ # fallthrough to the TEXT branch below
+
+ elif ctype == ContextType.IMAGE:
+ file_cache.add(session_id, content, file_type="image")
+ logger.info(f"[Slack] Image cached for session {session_id}, waiting for query...")
+ return
+ elif ctype == ContextType.FILE:
+ file_cache.add(session_id, content, file_type="file")
+ logger.info(f"[Slack] File cached for session {session_id}: {content}")
+ return
+
+ if ctype == ContextType.TEXT:
+ # Fast-path: /cancel mirrors Web channel behaviour
+ if (content or "").strip().lower() in ("/cancel", "cancel"):
+ self._do_cancel(session_id, channel_id, event)
+ return
+
+ cached_files = file_cache.get(session_id)
+ if cached_files:
+ refs = []
+ for fi in cached_files:
+ ftype = fi["type"]
+ tag = ftype if ftype in ("image", "video") else "file"
+ refs.append(f"[{tag}: {fi['path']}]")
+ slack_msg.content = (slack_msg.content or "") + "\n" + "\n".join(refs)
+ file_cache.clear(session_id)
+ logger.info(f"[Slack] Attached {len(cached_files)} cached file(s) to query")
+
+ # Reply in the originating thread when present, else start one on this msg
+ thread_ts = event.get("thread_ts") or ts
+
+ context = self._compose_context(
+ slack_msg.ctype,
+ slack_msg.content,
+ isgroup=is_group,
+ msg=slack_msg,
+ # Replies go back into the thread, no manual @mention needed
+ no_need_at=True,
+ )
+ if context:
+ context["session_id"] = session_id
+ context["receiver"] = channel_id
+ context["slack_channel"] = channel_id
+ context["slack_thread_ts"] = thread_ts if is_group else None
+ self.produce(context)
+ logger.debug(f"[Slack] received: type={ctype}, content={str(slack_msg.content)[:80]}")
+ except Exception as e:
+ logger.error(f"[Slack] _handle_event error: {e}", exc_info=True)
+
+ def _do_cancel(self, session_id: str, channel_id: str, event: dict):
+ """Fast-path: /cancel calls cancel_session directly without going through agent."""
+ try:
+ from agent.protocol import get_cancel_registry
+ cancelled = get_cancel_registry().cancel_session(session_id)
+ text = "Current task cancelled." if cancelled else "No running task to cancel."
+ thread_ts = event.get("thread_ts") or event.get("ts")
+ self._client.chat_postMessage(channel=channel_id, text=text, thread_ts=thread_ts)
+ logger.info(f"[Slack] /cancel session={session_id}, cancelled={cancelled}")
+ except Exception as e:
+ logger.error(f"[Slack] /cancel error: {e}", exc_info=True)
+
+ def _parse_event(self, event: dict):
+ """Parse a slack event and return (ctype, content, caption).
+
+ - content is text for ContextType.TEXT, otherwise the local file path
+ - caption is the optional text accompanying a file; empty for plain text
+ """
+ text = (event.get("text") or "").strip()
+ files = event.get("files") or []
+
+ if files:
+ # Handle the first attachment; caption is the accompanying message text
+ f = files[0]
+ mimetype = (f.get("mimetype") or "").lower()
+ url = f.get("url_private_download") or f.get("url_private")
+ name = f.get("name") or f.get("id") or "file"
+ if not url:
+ return (None, None, "")
+ path = self._download_file(url, name)
+ if not path:
+ return (None, None, "")
+ if mimetype.startswith("image/"):
+ return (ContextType.IMAGE, path, text)
+ return (ContextType.FILE, path, text)
+
+ if text:
+ return (ContextType.TEXT, text, "")
+
+ return (None, None, "")
+
+ def _download_file(self, url: str, name: str):
+ """Download a Slack private file (requires bot token auth) to local tmp dir."""
+ try:
+ headers = {"Authorization": f"Bearer {self.bot_token}"}
+ resp = requests.get(url, headers=headers, timeout=60, stream=True)
+ resp.raise_for_status()
+ tmp_dir = SlackMessage.get_tmp_dir()
+ # Sanitize the name and keep it unique-ish via the url tail
+ safe_name = re.sub(r"[^\w.\-]", "_", name)
+ local_path = os.path.join(tmp_dir, safe_name)
+ with open(local_path, "wb") as fp:
+ for chunk in resp.iter_content(chunk_size=8192):
+ if chunk:
+ fp.write(chunk)
+ logger.debug(f"[Slack] downloaded {name} -> {local_path}")
+ return local_path
+ except Exception as e:
+ logger.error(f"[Slack] download_file failed ({name}): {e}")
+ return None
+
+ # ------------------------------------------------------------------
+ # Channel trigger logic
+ # ------------------------------------------------------------------
+
+ def _should_reply_in_channel(self, event: dict) -> bool:
+ """Decide whether to reply to a plain channel message (no @mention).
+
+ app_mention already handles explicit @bot, so here we only deal with
+ follow-up messages. `all` replies to every message; `mention_or_reply`
+ replies inside threads the bot already participates in.
+ """
+ mode = conf().get("slack_group_trigger", "mention_or_reply")
+ if mode == "all":
+ return True
+ if mode == "mention_only":
+ return False
+ # mention_or_reply: follow up only within an existing thread
+ return bool(event.get("thread_ts"))
+
+ def _strip_at_mention(self, content: str) -> str:
+ """Strip <@BOT_USER_ID> from channel text."""
+ if not content or not self.bot_user_id:
+ return content
+ pattern = re.compile(r"<@" + re.escape(self.bot_user_id) + r">", re.IGNORECASE)
+ return pattern.sub("", content).strip()
+
+ @staticmethod
+ def _compute_session_id(event: dict, is_group: bool) -> str:
+ channel_id = event.get("channel", "")
+ user_id = event.get("user", "")
+ if is_group:
+ if conf().get("group_shared_session", True):
+ return f"slack_channel_{channel_id}"
+ return f"slack_channel_{channel_id}_{user_id}"
+ return f"slack_user_{user_id}"
+
+ # ------------------------------------------------------------------
+ # Override _compose_context: skip the parent's group whitelist/at checks
+ # (already handled via _should_reply_in_channel). Same idea as telegram.
+ # ------------------------------------------------------------------
+
+ def _compose_context(self, ctype: ContextType, content, **kwargs):
+ context = Context(ctype, content)
+ context.kwargs = kwargs
+ if "channel_type" not in context:
+ context["channel_type"] = self.channel_type
+ if "origin_ctype" not in context:
+ context["origin_ctype"] = ctype
+
+ cmsg = context["msg"]
+ if cmsg.is_group:
+ if conf().get("group_shared_session", True):
+ context["session_id"] = cmsg.other_user_id
+ else:
+ context["session_id"] = f"{cmsg.from_user_id}:{cmsg.other_user_id}"
+ else:
+ context["session_id"] = cmsg.from_user_id
+ context["receiver"] = cmsg.other_user_id
+
+ if ctype == ContextType.TEXT:
+ img_match_prefix = check_prefix(content, conf().get("image_create_prefix"))
+ if img_match_prefix:
+ content = content.replace(img_match_prefix, "", 1)
+ context.type = ContextType.IMAGE_CREATE
+ else:
+ context.type = ContextType.TEXT
+ context.content = (content or "").strip()
+ if "desire_rtype" not in context and conf().get("always_reply_voice"):
+ context["desire_rtype"] = ReplyType.VOICE
+ elif ctype == ContextType.VOICE:
+ if "desire_rtype" not in context and (
+ conf().get("voice_reply_voice") or conf().get("always_reply_voice")
+ ):
+ context["desire_rtype"] = ReplyType.VOICE
+
+ return context
+
+ # ------------------------------------------------------------------
+ # Outbound: ChatChannel.send -> Slack Web API
+ # ------------------------------------------------------------------
+
+ def send(self, reply: Reply, context: Context):
+ """Called from cow's sync main thread; Slack Web client is sync-safe."""
+ if self._client is None:
+ logger.warning("[Slack] client not ready, drop reply")
+ return
+
+ channel_id = context.get("slack_channel")
+ thread_ts = context.get("slack_thread_ts")
+ if not channel_id:
+ logger.warning("[Slack] no slack_channel in context, drop reply")
+ return
+
+ try:
+ self._do_send(reply, channel_id, thread_ts)
+ logger.info(f"[Slack] sent reply (type={reply.type}, channel={channel_id})")
+ except Exception as e:
+ logger.error(f"[Slack] send failed: {e}", exc_info=True)
+
+ def _do_send(self, reply: Reply, channel_id: str, thread_ts):
+ rtype = reply.type
+ content = reply.content
+
+ if rtype in (ReplyType.TEXT, ReplyType.INFO, ReplyType.ERROR):
+ text = str(content) if content is not None else ""
+ if not text:
+ return
+ # Slack caps a message around 40k chars; split conservatively
+ for chunk in _split_text(text, 3500):
+ self._client.chat_postMessage(channel=channel_id, text=chunk, thread_ts=thread_ts)
+
+ elif rtype == ReplyType.IMAGE:
+ # Already a local BytesIO; upload it directly
+ content.seek(0)
+ self._client.files_upload_v2(
+ channel=channel_id, file=content, filename="image.png", thread_ts=thread_ts,
+ )
+
+ elif rtype == ReplyType.IMAGE_URL:
+ url = str(content)
+ if url.startswith("file://"):
+ local = url[7:]
+ self._client.files_upload_v2(
+ channel=channel_id, file=local, thread_ts=thread_ts,
+ )
+ else:
+ # Post the URL as text; Slack will unfurl it as an image preview
+ self._client.chat_postMessage(channel=channel_id, text=url, thread_ts=thread_ts)
+
+ elif rtype in (ReplyType.VOICE, ReplyType.FILE):
+ local = content[7:] if isinstance(content, str) and content.startswith("file://") else content
+ caption = getattr(reply, "text_content", None) or None
+ self._client.files_upload_v2(
+ channel=channel_id, file=local, initial_comment=caption, thread_ts=thread_ts,
+ )
+
+ else:
+ # Fallback: send as plain text
+ self._client.chat_postMessage(channel=channel_id, text=str(content), thread_ts=thread_ts)
+
+
+def _split_text(text: str, limit: int):
+ """Split long text preferring line breaks to keep markdown structure intact."""
+ if len(text) <= limit:
+ yield text
+ return
+ buf = []
+ size = 0
+ for line in text.splitlines(keepends=True):
+ if size + len(line) > limit and buf:
+ yield "".join(buf)
+ buf, size = [], 0
+ # Hard-split single lines that exceed the limit
+ while len(line) > limit:
+ yield line[:limit]
+ line = line[limit:]
+ buf.append(line)
+ size += len(line)
+ if buf:
+ yield "".join(buf)
diff --git a/channel/slack/slack_message.py b/channel/slack/slack_message.py
new file mode 100644
index 00000000..39f215bd
--- /dev/null
+++ b/channel/slack/slack_message.py
@@ -0,0 +1,60 @@
+"""
+Slack message adapter.
+
+Convert a Slack event payload into cow's unified ChatMessage.
+File downloads are NOT performed here; the channel layer downloads files
+on demand because it needs the bot token for authenticated download URLs.
+"""
+import os
+
+from bridge.context import ContextType
+from channel.chat_message import ChatMessage
+from common.utils import expand_path
+from config import conf
+
+
+class SlackMessage(ChatMessage):
+ """Wrap a Slack event into the unified ChatMessage."""
+
+ def __init__(self, event: dict, is_group: bool = False, bot_user_id: str = "",
+ ctype: ContextType = ContextType.TEXT, content: str = ""):
+ super().__init__(event)
+ # Basic fields
+ self.msg_id = event.get("client_msg_id") or event.get("ts") or ""
+ try:
+ self.create_time = int(float(event.get("ts", 0)))
+ except (TypeError, ValueError):
+ self.create_time = 0
+ self.ctype = ctype
+ self.content = content
+
+ # Sender / chat info
+ from_user_id = event.get("user", "unknown")
+ channel_id = event.get("channel", "")
+ self.from_user_id = from_user_id
+ self.from_user_nickname = from_user_id
+ self.to_user_id = bot_user_id or "slack_bot"
+ self.to_user_nickname = bot_user_id or "slack_bot"
+
+ self.is_group = is_group
+ if is_group:
+ # Channel chat: other_user_id = channel_id, actual_user_id = sender id
+ self.other_user_id = channel_id
+ self.other_user_nickname = channel_id
+ self.actual_user_id = from_user_id
+ self.actual_user_nickname = from_user_id
+ else:
+ # DM: use channel_id so replies go back to the same DM channel
+ self.other_user_id = channel_id or from_user_id
+ self.other_user_nickname = from_user_id
+
+ # Whether the bot was triggered by @-mention (set by channel layer)
+ self.is_at = False
+
+ @staticmethod
+ def get_tmp_dir() -> str:
+ """Local download directory, aligned with other channels (agent_workspace/tmp)."""
+ workspace_root = expand_path(conf().get("agent_workspace", "~/cow"))
+ tmp_dir = os.path.join(workspace_root, "tmp")
+ os.makedirs(tmp_dir, exist_ok=True)
+ return tmp_dir
diff --git a/channel/telegram/__init__.py b/channel/telegram/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/channel/telegram/telegram_channel.py b/channel/telegram/telegram_channel.py
new file mode 100644
index 00000000..9e40c59f
--- /dev/null
+++ b/channel/telegram/telegram_channel.py
@@ -0,0 +1,719 @@
+"""
+Telegram channel via Bot API (long polling mode).
+
+Features:
+- Single chat & group chat (text / photo / voice / video / document)
+- Group trigger: @mention or reply-to-bot (configurable)
+- /cancel fast-path matches Web channel behaviour
+- Auto-register bot commands menu on startup (mirrors Web slash menu)
+- Optional HTTP/SOCKS5 proxy support for restricted networks
+
+Implementation note:
+ python-telegram-bot is async-first. We run the bot inside a dedicated
+ thread with its own asyncio loop so the rest of cow (which is sync)
+ stays untouched. Inbound updates are dispatched onto cow's existing
+ sync ChatChannel.produce() pipeline; outbound send() schedules
+ coroutines back onto that loop via asyncio.run_coroutine_threadsafe.
+"""
+
+import asyncio
+import os
+import re
+import threading
+
+from bridge.context import Context, ContextType
+from bridge.reply import Reply, ReplyType
+from channel.chat_channel import ChatChannel, check_prefix
+from channel.telegram.telegram_message import TelegramMessage
+from common.expired_dict import ExpiredDict
+from common.log import logger
+from common.singleton import singleton
+from config import conf
+
+# Bot command menu, aligned with Web slash commands.
+# Top-level commands only; sub-commands are entered with a space (e.g. "/skill list").
+TELEGRAM_BOT_COMMANDS = [
+ ("help", "Show command help"),
+ ("status", "Show running status"),
+ ("context", "View/clear conversation context (sub: clear)"),
+ ("skill", "Manage skills (list/search/install/...)"),
+ ("memory", "Manage memory (sub: dream)"),
+ ("knowledge", "Manage knowledge base (list/on/off)"),
+ ("config", "Show current config"),
+ ("cancel", "Cancel running agent task"),
+ ("logs", "Show recent logs"),
+ ("version", "Show version"),
+]
+
+
+@singleton
+class TelegramChannel(ChatChannel):
+ NOT_SUPPORT_REPLYTYPE = []
+
+ def __init__(self):
+ super().__init__()
+ self.bot_token = ""
+ self.bot_username = "" # used for @-mention matching
+ self._bot = None
+ self._application = None
+ self._loop = None
+ self._loop_thread = None
+ self._stop_event = threading.Event()
+ # Idempotent dedup; TG occasionally redelivers the same update on flaky networks
+ self._received_msgs = ExpiredDict(60 * 60 * 1)
+
+ # Disable group whitelist / prefix checks (we handle triggering ourselves
+ # in _should_reply_in_group), aligned with feishu / wecom_bot channels.
+ conf()["group_name_white_list"] = ["ALL_GROUP"]
+ conf()["single_chat_prefix"] = [""]
+
+ # ------------------------------------------------------------------
+ # Lifecycle
+ # ------------------------------------------------------------------
+
+ def startup(self):
+ self.bot_token = conf().get("telegram_token", "")
+ if not self.bot_token:
+ err = "[Telegram] telegram_token is required"
+ logger.error(err)
+ self.report_startup_error(err)
+ return
+
+ try:
+ from telegram.ext import (
+ Application,
+ MessageHandler,
+ CommandHandler,
+ filters,
+ )
+ except ImportError:
+ err = (
+ "[Telegram] python-telegram-bot is not installed. "
+ "Run: pip install python-telegram-bot"
+ )
+ logger.error(err)
+ self.report_startup_error(err)
+ return
+
+ # Run the asyncio event loop in a dedicated thread so the sync cow body
+ # is untouched.
+ self._loop = asyncio.new_event_loop()
+
+ def _run_loop():
+ asyncio.set_event_loop(self._loop)
+ try:
+ self._loop.run_until_complete(self._async_main(Application, MessageHandler, CommandHandler, filters))
+ except Exception as e:
+ logger.error(f"[Telegram] event loop crashed: {e}", exc_info=True)
+ self.report_startup_error(str(e))
+ finally:
+ try:
+ self._loop.close()
+ except Exception:
+ pass
+ logger.info("[Telegram] event loop exited")
+
+ self._loop_thread = threading.Thread(target=_run_loop, daemon=True, name="telegram-loop")
+ self._loop_thread.start()
+ # Block startup() until the loop thread exits, matching other channels'
+ # behaviour (startup is a blocking call).
+ self._loop_thread.join()
+
+ async def _async_main(self, Application, MessageHandler, CommandHandler, filters):
+ """Build Application, register handlers, and run polling."""
+ builder = Application.builder().token(self.bot_token)
+
+ # Proxy: prefer telegram_proxy config, fall back to HTTPS_PROXY env var
+ proxy_url = conf().get("telegram_proxy", "") or os.environ.get("HTTPS_PROXY", "")
+ if proxy_url:
+ try:
+ builder = builder.proxy(proxy_url).get_updates_proxy(proxy_url)
+ logger.info(f"[Telegram] using proxy: {proxy_url}")
+ except Exception as e:
+ logger.warning(f"[Telegram] proxy config failed, fallback to direct: {e}")
+
+ # Media uploads (photo/voice/video/document) over a proxy can be slow,
+ # bump read/write/connect/pool timeouts.
+ builder = (
+ builder
+ .read_timeout(60)
+ .write_timeout(120)
+ .connect_timeout(30)
+ .pool_timeout(30)
+ )
+
+ application = builder.build()
+ self._application = application
+ self._bot = application.bot
+
+ # Fetch our own username (needed for @-mention matching in groups)
+ try:
+ me = await self._bot.get_me()
+ self.bot_username = me.username or ""
+ self.name = self.bot_username # ChatChannel uses self.name to strip @-mention
+ logger.info(f"[Telegram] Bot logged in as @{self.bot_username} (id={me.id})")
+ except Exception as e:
+ err = f"[Telegram] get_me failed: {e}"
+ logger.error(err)
+ self.report_startup_error(err)
+ return
+
+ # Register the command menu (failure is non-fatal)
+ if conf().get("telegram_register_commands", True):
+ try:
+ from telegram import BotCommand
+ cmds = [BotCommand(name, desc) for name, desc in TELEGRAM_BOT_COMMANDS]
+ await self._bot.set_my_commands(cmds)
+ logger.info(f"[Telegram] Registered {len(cmds)} bot commands")
+ except Exception as e:
+ logger.warning(f"[Telegram] set_my_commands failed: {e}")
+
+ # Handlers:
+ # 1) /cancel uses the fast-path
+ application.add_handler(CommandHandler("cancel", self._on_cancel))
+ # 2) Normal messages (text + media)
+ application.add_handler(MessageHandler(filters.ALL & ~filters.COMMAND, self._on_message))
+ # 3) Other slash commands are forwarded as plain text for the agent to handle
+ application.add_handler(MessageHandler(filters.COMMAND, self._on_command_passthrough))
+
+ # Start polling. drop_pending_updates avoids replaying backlog after restart.
+ # Transient "Server disconnected" / RemoteProtocolError during get_updates
+ # are common over proxies/flaky networks; PTB's network loop auto-retries,
+ # so we only need to keep the noise down (see _quiet_polling_network_errors).
+ self._quiet_polling_network_errors()
+ logger.info("[Telegram] Starting long polling...")
+ await application.initialize()
+ await application.start()
+ await application.updater.start_polling(
+ drop_pending_updates=True,
+ # Long-poll hold time on the server side; smaller value = reconnect more
+ # often but each hung connection fails faster.
+ timeout=30,
+ # Retry forever on transient get_updates network errors instead of giving up.
+ bootstrap_retries=-1,
+ )
+ self.report_startup_success()
+ logger.info("[Telegram] ✅ Telegram bot ready, polling for updates")
+
+ # Block until stop()
+ try:
+ while not self._stop_event.is_set():
+ await asyncio.sleep(0.5)
+ finally:
+ try:
+ await application.updater.stop()
+ await application.stop()
+ await application.shutdown()
+ except Exception as e:
+ logger.warning(f"[Telegram] shutdown error: {e}")
+
+ @staticmethod
+ def _quiet_polling_network_errors():
+ """Downgrade PTB's noisy 'Exception happened while polling for updates' logs.
+
+ These transient get_updates errors (RemoteProtocolError / NetworkError /
+ TimedOut, typically over a proxy) are auto-retried by PTB's network loop,
+ so logging the full traceback at ERROR is just noise. We attach a filter
+ that drops these specific records while leaving real errors untouched.
+ """
+ import logging
+
+ class _PollingNoiseFilter(logging.Filter):
+ _NEEDLES = (
+ "Exception happened while polling for updates",
+ "Server disconnected without sending a response",
+ )
+
+ def filter(self, record: logging.LogRecord) -> bool:
+ try:
+ msg = record.getMessage()
+ except Exception:
+ return True
+ if any(n in msg for n in self._NEEDLES):
+ # Keep a single-line breadcrumb at DEBUG, drop the traceback.
+ logger.debug(f"[Telegram] transient polling network error (auto-retrying): {msg.splitlines()[0]}")
+ return False
+ return True
+
+ noise_filter = _PollingNoiseFilter()
+ for name in ("telegram.ext.Updater", "telegram.ext._updater", "telegram.ext"):
+ logging.getLogger(name).addFilter(noise_filter)
+
+ def stop(self):
+ logger.info("[Telegram] stop() called")
+ self._stop_event.set()
+ if self._loop_thread and self._loop_thread.is_alive():
+ try:
+ self._loop_thread.join(timeout=10)
+ except Exception:
+ pass
+ logger.info("[Telegram] stop() completed")
+
+ # ------------------------------------------------------------------
+ # Inbound: telegram update -> ChatMessage -> ChatChannel.produce
+ # ------------------------------------------------------------------
+
+ async def _on_cancel(self, update, _context):
+ """Fast-path: /cancel calls cancel_session directly without going through agent."""
+ try:
+ from agent.protocol import get_cancel_registry
+ session_id = self._compute_session_id(update)
+ cancelled = get_cancel_registry().cancel_session(session_id)
+ text = "Current task cancelled." if cancelled else "No running task to cancel."
+ await update.effective_message.reply_text(text)
+ logger.info(f"[Telegram] /cancel session={session_id}, cancelled={cancelled}")
+ except Exception as e:
+ logger.error(f"[Telegram] /cancel error: {e}", exc_info=True)
+ try:
+ await update.effective_message.reply_text(f"⚠️ /cancel failed: {e}")
+ except Exception:
+ pass
+
+ async def _on_command_passthrough(self, update, _context):
+ """All non-/cancel commands fall through to plain message handling."""
+ await self._on_message(update, _context)
+
+ async def _on_message(self, update, _context):
+ """Telegram update entry: parse message -> build ChatMessage -> produce()."""
+ try:
+ message = update.effective_message
+ chat = update.effective_chat
+ if not message or not chat:
+ return
+
+ # Idempotent dedup
+ msg_uid = f"{chat.id}:{message.message_id}"
+ if self._received_msgs.get(msg_uid):
+ return
+ self._received_msgs[msg_uid] = True
+
+ is_group = chat.type in ("group", "supergroup")
+
+ # Debug log: helpful when group messages are silently dropped
+ if is_group:
+ logger.debug(
+ f"[Telegram] group update received: chat_id={chat.id}, "
+ f"text={(message.text or message.caption or '')[:40]!r}, "
+ f"reply_to_bot={bool(message.reply_to_message and message.reply_to_message.from_user and message.reply_to_message.from_user.username == self.bot_username)}"
+ )
+
+ # Group trigger gate (silently drop if not triggered)
+ if is_group and not self._should_reply_in_group(update):
+ logger.debug(f"[Telegram] group message not triggered (need @{self.bot_username} or reply), skip")
+ return
+
+ # Parse message type + download media if needed.
+ # Media messages with caption return both the local path and the caption text.
+ ctype, content, caption = await self._parse_message(message)
+ if ctype is None:
+ logger.debug(f"[Telegram] unsupported message type, skip. msg={message}")
+ return
+
+ # Strip @bot mention for group text/caption
+ if is_group and self.bot_username:
+ if ctype == ContextType.TEXT and content:
+ content = self._strip_at_mention(content)
+ if caption:
+ caption = self._strip_at_mention(caption)
+
+ tg_msg = TelegramMessage(
+ update,
+ is_group=is_group,
+ bot_username=self.bot_username,
+ ctype=ctype,
+ content=content,
+ )
+ tg_msg.is_at = is_group # If we got here in a group, the bot is mentioned/replied
+
+ # File cache: standalone media goes into cache, the next text query attaches them
+ from channel.file_cache import get_file_cache
+ file_cache = get_file_cache()
+ session_id = self._compute_session_id(update)
+
+ # Media + caption together: treat as a complete query and bypass the cache
+ if ctype in (ContextType.IMAGE, ContextType.FILE) and caption:
+ tag = "image" if ctype == ContextType.IMAGE else "file"
+ merged_text = f"{caption}\n[{tag}: {content}]"
+ tg_msg.ctype = ContextType.TEXT
+ tg_msg.content = merged_text
+ ctype = ContextType.TEXT
+ logger.info(f"[Telegram] Media+caption merged for session {session_id}")
+ # fallthrough to the TEXT branch below
+
+ elif ctype == ContextType.IMAGE:
+ file_cache.add(session_id, content, file_type="image")
+ logger.info(f"[Telegram] Image cached for session {session_id}, waiting for query...")
+ return
+ elif ctype == ContextType.FILE:
+ file_cache.add(session_id, content, file_type="file")
+ logger.info(f"[Telegram] File cached for session {session_id}: {content}")
+ return
+
+ if ctype == ContextType.TEXT:
+ cached_files = file_cache.get(session_id)
+ if cached_files:
+ refs = []
+ for fi in cached_files:
+ ftype = fi["type"]
+ tag = ftype if ftype in ("image", "video") else "file"
+ refs.append(f"[{tag}: {fi['path']}]")
+ tg_msg.content = (tg_msg.content or "") + "\n" + "\n".join(refs)
+ file_cache.clear(session_id)
+ logger.info(f"[Telegram] Attached {len(cached_files)} cached file(s) to query")
+
+ # Dispatch to cow main pipeline (reuses ChatChannel._compose_context routing)
+ context = self._compose_context(
+ tg_msg.ctype,
+ tg_msg.content,
+ isgroup=is_group,
+ msg=tg_msg,
+ )
+ if context:
+ context["session_id"] = session_id
+ context["receiver"] = str(chat.id)
+ context["telegram_chat_id"] = chat.id
+ context["telegram_reply_to_msg_id"] = message.message_id if is_group else None
+ self.produce(context)
+ logger.debug(f"[Telegram] received: type={ctype}, content={str(tg_msg.content)[:80]}")
+
+ except Exception as e:
+ logger.error(f"[Telegram] _on_message error: {e}", exc_info=True)
+
+ async def _parse_message(self, message):
+ """Parse a telegram message and return (ctype, content, caption).
+
+ - content is text for ContextType.TEXT, otherwise the local file path
+ - caption is the optional text accompanying a media message; empty for plain text
+ """
+ caption = (message.caption or "").strip()
+
+ if message.photo:
+ largest = message.photo[-1]
+ path = await self._download_file(largest.file_id, suffix=".jpg")
+ return (ContextType.IMAGE, path, caption) if path else (None, None, "")
+
+ if message.voice or message.audio:
+ audio_obj = message.voice or message.audio
+ suffix = ".ogg" if message.voice else (
+ "." + (audio_obj.mime_type.split("/")[-1] if getattr(audio_obj, "mime_type", "") else "mp3")
+ )
+ path = await self._download_file(audio_obj.file_id, suffix=suffix)
+ return (ContextType.VOICE, path, caption) if path else (None, None, "")
+
+ if message.video or message.video_note:
+ video_obj = message.video or message.video_note
+ path = await self._download_file(video_obj.file_id, suffix=".mp4")
+ return (ContextType.FILE, path, caption) if path else (None, None, "")
+
+ if message.document:
+ doc = message.document
+ ext = ""
+ if doc.file_name and "." in doc.file_name:
+ ext = "." + doc.file_name.rsplit(".", 1)[-1]
+ path = await self._download_file(doc.file_id, suffix=ext, original_name=doc.file_name)
+ if not path:
+ return (None, None, "")
+ # Image-typed documents (user picked "send as file") are treated as images
+ mime = (doc.mime_type or "").lower()
+ if mime.startswith("image/"):
+ return (ContextType.IMAGE, path, caption)
+ return (ContextType.FILE, path, caption)
+
+ if message.text:
+ return (ContextType.TEXT, message.text.strip(), "")
+
+ return (None, None, "")
+
+ async def _download_file(self, file_id: str, suffix: str = "", original_name: str = ""):
+ """Download via bot.get_file into the local tmp dir; return path or None on failure."""
+ try:
+ f = await self._bot.get_file(file_id)
+ tmp_dir = TelegramMessage.get_tmp_dir()
+ base = original_name or f"{file_id}{suffix or ''}"
+ # Prefix with file_id to avoid name collisions / weird chars
+ safe_name = f"{file_id}_{base}" if original_name else base
+ local_path = os.path.join(tmp_dir, safe_name)
+ await f.download_to_drive(custom_path=local_path)
+ logger.debug(f"[Telegram] downloaded file_id={file_id} -> {local_path}")
+ return local_path
+ except Exception as e:
+ logger.error(f"[Telegram] download_file failed (file_id={file_id}): {e}")
+ return None
+
+ # ------------------------------------------------------------------
+ # Group trigger logic
+ # ------------------------------------------------------------------
+
+ def _should_reply_in_group(self, update) -> bool:
+ """Decide whether to reply to a group message based on configuration."""
+ mode = conf().get("telegram_group_trigger", "mention_or_reply")
+ if mode == "all":
+ return True
+
+ message = update.effective_message
+ if not message:
+ return False
+
+ # 1) Mentioned
+ if self.bot_username and self._is_mentioned(message, self.bot_username):
+ return True
+
+ # 2) Reply to a bot message
+ if mode == "mention_or_reply":
+ reply = message.reply_to_message
+ if reply and reply.from_user and reply.from_user.username == self.bot_username:
+ return True
+
+ return False
+
+ @staticmethod
+ def _is_mentioned(message, bot_username: str) -> bool:
+ """Check whether entities/caption_entities contain a @mention of the bot."""
+ bot_at = "@" + bot_username.lower()
+ text = (message.text or message.caption or "").lower()
+ if bot_at in text:
+ return True
+ # Also check entities strictly to support text_mention (no-username @)
+ for ent in (message.entities or []) + (message.caption_entities or []):
+ if ent.type == "mention":
+ src = message.text or message.caption or ""
+ if src[ent.offset: ent.offset + ent.length].lower() == bot_at:
+ return True
+ return False
+
+ def _strip_at_mention(self, content: str) -> str:
+ """Strip @bot_username from group text (case-insensitive)."""
+ if not content or not self.bot_username:
+ return content
+ pattern = re.compile(r"@" + re.escape(self.bot_username), re.IGNORECASE)
+ return pattern.sub("", content).strip()
+
+ @staticmethod
+ def _compute_session_id(update) -> str:
+ chat = update.effective_chat
+ user = update.effective_user
+ is_group = chat.type in ("group", "supergroup")
+ if is_group:
+ if conf().get("group_shared_session", True):
+ return f"tg_group_{chat.id}"
+ return f"tg_group_{chat.id}_{user.id}"
+ return f"tg_user_{user.id}"
+
+ # ------------------------------------------------------------------
+ # Override _compose_context: skip the parent's group whitelist/at checks
+ # (already handled in _on_message via _should_reply_in_group). Same idea
+ # as the feishu channel.
+ # ------------------------------------------------------------------
+
+ def _compose_context(self, ctype: ContextType, content, **kwargs):
+ context = Context(ctype, content)
+ context.kwargs = kwargs
+ if "channel_type" not in context:
+ context["channel_type"] = self.channel_type
+ if "origin_ctype" not in context:
+ context["origin_ctype"] = ctype
+
+ cmsg = context["msg"]
+ if cmsg.is_group:
+ if conf().get("group_shared_session", True):
+ context["session_id"] = cmsg.other_user_id
+ else:
+ context["session_id"] = f"{cmsg.from_user_id}:{cmsg.other_user_id}"
+ else:
+ context["session_id"] = cmsg.from_user_id
+ context["receiver"] = cmsg.other_user_id
+
+ if ctype == ContextType.TEXT:
+ img_match_prefix = check_prefix(content, conf().get("image_create_prefix"))
+ if img_match_prefix:
+ content = content.replace(img_match_prefix, "", 1)
+ context.type = ContextType.IMAGE_CREATE
+ else:
+ context.type = ContextType.TEXT
+ context.content = (content or "").strip()
+ if "desire_rtype" not in context and conf().get("always_reply_voice"):
+ context["desire_rtype"] = ReplyType.VOICE
+ elif ctype == ContextType.VOICE:
+ if "desire_rtype" not in context and (
+ conf().get("voice_reply_voice") or conf().get("always_reply_voice")
+ ):
+ context["desire_rtype"] = ReplyType.VOICE
+
+ return context
+
+ # ------------------------------------------------------------------
+ # Outbound: ChatChannel.send -> Telegram API
+ # ------------------------------------------------------------------
+
+ def send(self, reply: Reply, context: Context):
+ """Called from cow's sync main thread; we marshal the coroutine onto the loop thread."""
+ if self._loop is None or self._bot is None:
+ logger.warning("[Telegram] bot not ready, drop reply")
+ return
+
+ chat_id = context.get("telegram_chat_id")
+ reply_to = context.get("telegram_reply_to_msg_id")
+ if chat_id is None:
+ logger.warning("[Telegram] no telegram_chat_id in context, drop reply")
+ return
+
+ coro = self._async_send(reply, chat_id, reply_to)
+ try:
+ future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+ # Media uploads through a proxy can be slow; let PTB's own timeouts win
+ future.result(timeout=180)
+ except Exception as e:
+ logger.error(f"[Telegram] send failed: {e}")
+
+ # Number of retries for transient network errors (proxy hiccups etc.)
+ _SEND_RETRIES = 2
+ _SEND_RETRY_BACKOFF = 2.0 # seconds
+
+ async def _send_with_retry(self, send_fn, *, label: str):
+ """Run a single Telegram API call with retries for transient network errors."""
+ from telegram.error import NetworkError, TimedOut
+ last_err = None
+ for attempt in range(self._SEND_RETRIES + 1):
+ try:
+ return await send_fn()
+ except (NetworkError, TimedOut) as e:
+ last_err = e
+ if attempt >= self._SEND_RETRIES:
+ break
+ wait = self._SEND_RETRY_BACKOFF * (attempt + 1)
+ logger.warning(
+ f"[Telegram] {label} transient error (attempt {attempt + 1}/"
+ f"{self._SEND_RETRIES + 1}): {e}; retry in {wait}s"
+ )
+ await asyncio.sleep(wait)
+ raise last_err
+
+ async def _async_send(self, reply: Reply, chat_id, reply_to_msg_id):
+ try:
+ rtype = reply.type
+ content = reply.content
+
+ if rtype == ReplyType.TEXT or rtype == ReplyType.INFO or rtype == ReplyType.ERROR:
+ # Telegram caps a single text message at 4096 chars; auto-split
+ text = str(content) if content is not None else ""
+ if not text:
+ return
+ for chunk in _split_text(text, 4000):
+ await self._send_with_retry(
+ lambda c=chunk: self._bot.send_message(
+ chat_id=chat_id,
+ text=c,
+ reply_to_message_id=reply_to_msg_id,
+ # Avoid failing the whole send if reply_to was deleted
+ allow_sending_without_reply=True,
+ ),
+ label="send_message",
+ )
+
+ elif rtype == ReplyType.IMAGE:
+ # Already a local BytesIO; send it directly
+ content.seek(0)
+ await self._send_with_retry(
+ lambda: self._bot.send_photo(
+ chat_id=chat_id,
+ photo=content,
+ reply_to_message_id=reply_to_msg_id,
+ allow_sending_without_reply=True,
+ ),
+ label="send_photo",
+ )
+
+ elif rtype == ReplyType.IMAGE_URL:
+ url = str(content)
+ if url.startswith("file://"):
+ local = url[7:]
+ # Open inside the lambda so each retry gets a fresh stream
+ async def _send_local_photo():
+ with open(local, "rb") as f:
+ return await self._bot.send_photo(
+ chat_id=chat_id, photo=f,
+ reply_to_message_id=reply_to_msg_id,
+ allow_sending_without_reply=True,
+ )
+ await self._send_with_retry(_send_local_photo, label="send_photo(file)")
+ else:
+ await self._send_with_retry(
+ lambda: self._bot.send_photo(
+ chat_id=chat_id, photo=url,
+ reply_to_message_id=reply_to_msg_id,
+ allow_sending_without_reply=True,
+ ),
+ label="send_photo(url)",
+ )
+
+ elif rtype == ReplyType.VOICE:
+ local = content[7:] if isinstance(content, str) and content.startswith("file://") else content
+ async def _send_voice():
+ with open(local, "rb") as f:
+ return await self._bot.send_voice(
+ chat_id=chat_id, voice=f,
+ reply_to_message_id=reply_to_msg_id,
+ allow_sending_without_reply=True,
+ )
+ await self._send_with_retry(_send_voice, label="send_voice")
+
+ elif rtype == ReplyType.FILE:
+ # Videos go through send_video, everything else through send_document
+ local = content[7:] if isinstance(content, str) and content.startswith("file://") else content
+ # File replies may carry an accompanying text caption
+ caption = getattr(reply, "text_content", None) or None
+ is_video = isinstance(local, str) and local.lower().endswith(
+ (".mp4", ".mov", ".avi", ".mkv", ".webm")
+ )
+
+ async def _send_file():
+ with open(local, "rb") as f:
+ if is_video:
+ return await self._bot.send_video(
+ chat_id=chat_id, video=f, caption=caption,
+ reply_to_message_id=reply_to_msg_id,
+ allow_sending_without_reply=True,
+ )
+ return await self._bot.send_document(
+ chat_id=chat_id, document=f, caption=caption,
+ reply_to_message_id=reply_to_msg_id,
+ allow_sending_without_reply=True,
+ )
+ await self._send_with_retry(_send_file, label="send_video" if is_video else "send_document")
+
+ else:
+ # Fallback: send as plain text
+ await self._send_with_retry(
+ lambda: self._bot.send_message(
+ chat_id=chat_id, text=str(content),
+ reply_to_message_id=reply_to_msg_id,
+ allow_sending_without_reply=True,
+ ),
+ label="send_message(fallback)",
+ )
+
+ logger.info(f"[Telegram] sent reply (type={rtype}, chat_id={chat_id})")
+
+ except Exception as e:
+ logger.error(f"[Telegram] _async_send error: {e}", exc_info=True)
+
+
+def _split_text(text: str, limit: int):
+ """Split long text preferring line breaks to keep markdown structure intact."""
+ if len(text) <= limit:
+ yield text
+ return
+ buf = []
+ size = 0
+ for line in text.splitlines(keepends=True):
+ if size + len(line) > limit and buf:
+ yield "".join(buf)
+ buf, size = [], 0
+ # Hard-split single lines that exceed the limit
+ while len(line) > limit:
+ yield line[:limit]
+ line = line[limit:]
+ buf.append(line)
+ size += len(line)
+ if buf:
+ yield "".join(buf)
diff --git a/channel/telegram/telegram_message.py b/channel/telegram/telegram_message.py
new file mode 100644
index 00000000..c97c6059
--- /dev/null
+++ b/channel/telegram/telegram_message.py
@@ -0,0 +1,62 @@
+"""
+Telegram message adapter.
+
+Convert a python-telegram-bot Update into cow's unified ChatMessage.
+File downloads are NOT performed here; the channel layer triggers
+bot.get_file() on demand because it requires the async event loop.
+"""
+import os
+
+from bridge.context import ContextType
+from channel.chat_message import ChatMessage
+from common.utils import expand_path
+from config import conf
+
+
+class TelegramMessage(ChatMessage):
+ """Wrap a Telegram Update into the unified ChatMessage."""
+
+ def __init__(self, update, is_group: bool = False, bot_username: str = "",
+ ctype: ContextType = ContextType.TEXT, content: str = ""):
+ super().__init__(update)
+ message = update.effective_message
+ chat = update.effective_chat
+ user = update.effective_user
+
+ # Basic fields
+ self.msg_id = str(message.message_id) if message else ""
+ self.create_time = int(message.date.timestamp()) if message and message.date else 0
+ self.ctype = ctype
+ self.content = content
+
+ # Sender / chat info
+ from_user_id = str(user.id) if user else "unknown"
+ from_user_nick = (
+ user.full_name if user and user.full_name else (user.username if user else "unknown")
+ )
+ self.from_user_id = from_user_id
+ self.from_user_nickname = from_user_nick or from_user_id
+ self.to_user_id = bot_username or "telegram_bot"
+ self.to_user_nickname = bot_username or "telegram_bot"
+
+ self.is_group = is_group
+ if is_group:
+ # Group: other_user_id = group_id, actual_user_id = sender id
+ self.other_user_id = str(chat.id)
+ self.other_user_nickname = chat.title or str(chat.id)
+ self.actual_user_id = from_user_id
+ self.actual_user_nickname = self.from_user_nickname
+ else:
+ self.other_user_id = from_user_id
+ self.other_user_nickname = self.from_user_nickname
+
+ # Whether the bot was triggered by @-mention or reply (set by channel layer)
+ self.is_at = False
+
+ @staticmethod
+ def get_tmp_dir() -> str:
+ """Local download directory, aligned with other channels (agent_workspace/tmp)."""
+ workspace_root = expand_path(conf().get("agent_workspace", "~/cow"))
+ tmp_dir = os.path.join(workspace_root, "tmp")
+ os.makedirs(tmp_dir, exist_ok=True)
+ return tmp_dir
diff --git a/channel/web/chat.html b/channel/web/chat.html
index 56ce808f..d90adb15 100644
--- a/channel/web/chat.html
+++ b/channel/web/chat.html
@@ -137,6 +137,11 @@
配置
+
+ 高级配置
+
@@ -850,6 +869,41 @@
+
+
+
+
+
+
+
+
+
+
+
模型管理
+
统一管理对话、视觉、语音、向量、图像、搜索能力
+
+
+ 添加厂商
+
+
+
+ Loading...
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ API Key
+
+
+
API Base
+
+
+ 留空将使用官方默认地址
+
+
+
+
+
+ 清除凭据
+ 取消
+ 保存
+
+
+
+
+| Capability | Description |
+| :--- | :--- |
+| [Planning](https://docs.cowagent.ai/en/intro/architecture) | Decomposes complex tasks and executes them step by step, looping over tools until the goal is reached |
+| [Memory](https://docs.cowagent.ai/en/memory/index) | Three-tier architecture (context → daily → core), automatic Deep Dream distillation, hybrid keyword + vector retrieval |
+| [Knowledge](https://docs.cowagent.ai/en/knowledge/index) | Auto-curates structured knowledge into a Markdown wiki, builds an evolving knowledge graph with visual browsing |
+| [Skills](https://docs.cowagent.ai/en/skills/index) | One-click install from [Skill Hub](https://skills.cowagent.ai/), GitHub, ClawHub; or create custom skills via natural-language conversation |
+| [Tools](https://docs.cowagent.ai/en/tools/index) | Built-in file I/O, terminal, browser, scheduler, memory retrieval, web search, and 10+ more tools — with native MCP integration |
+| [Channels](https://docs.cowagent.ai/en/channels/index) | Integrates with Web, WeChat, Feishu, DingTalk, WeCom, QQ, Official Accounts, Telegram, and Slack |
+| Multimodal | First-class support for text, images, voice, and files — recognition, generation, and delivery |
+| [Models](https://docs.cowagent.ai/en/models/index) | Claude, GPT, Gemini, DeepSeek, Qwen, GLM, Kimi, MiniMax, Doubao, and more — swap providers from the Web console with one click |
+| [Deploy](https://docs.cowagent.ai/en/guide/quick-start) | One-line installer, unified Web console, multiple deployment modes (local, Docker, server) |
+
-> [LinkAI](https://link-ai.tech/) 是面向企业和个人的一站式 AI 智能体平台，聚合多模态大模型、知识库、技能、工作流等能力，支持一键接入主流平台并管理，支持 SaaS、私有化部署等多种模式，可免部署在线运行[CowAgent 助理](https://link-ai.tech/cowagent/create)。
->
-> LinkAI 目前已在智能客服、私域运营、企业效率助手等场景积累了丰富的 AI 解决方案，在消费、健康、文教、科技制造等各行业沉淀了大模型落地应用的最佳实践，致力于帮助更多企业和开发者拥抱 AI 生产力。
+CowAgent is a complete **Agent Harness**: messages flow in through **Channels**; the **Agent Core** plans and reasons over memory, knowledge, and the available tools and skills; **Models** generate the response, which is sent back through the originating channel. Every layer is decoupled and independently extensible.
-**产品咨询和企业服务** 可联系产品客服：
-
-
+Read more in [Architecture](https://docs.cowagent.ai/en/intro/architecture).
-# ✉ 联系
+*The Web console is the default channel and the unified entry point to configure models, channels, skills, memory, and more.*
-欢迎提交PR、Issues进行反馈，以及通过 🌟Star 支持并关注项目更新。项目运行遇到问题可以查看 [常见问题列表](https://github.com/zhayujie/CowAgent/wiki/FAQs) ，以及前往 [Issues](https://github.com/zhayujie/CowAgent/issues) 中搜索。个人开发者可加入开源交流群参与更多讨论，企业用户可联系[产品客服](https://cdn.link-ai.tech/portal/linkai-customer-service.png)咨询。
+
+ 
+