kaiyuan/chatgpt-on-wechat
1
0
Fork 0
mirror of https://github.com/zhayujie/chatgpt-on-wechat.git synced 2026-07-19 12:47:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: make English the default docs language and fix link paths

Browse Source
This commit is contained in:
zhayujie
2026-05-31 17:52:22 +08:00
parent 126649f70f
commit 7bf4ef3d05
231 changed files with 8999 additions and 8974 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/zh/README.md
View File

@@ -13,8 +13,8 @@ CowAgent 轻量、易部署、可扩展，自由接入主流大模型，覆盖
<p align="center">
<a href="https://cowagent.ai/?lang=zh">🌐 官网</a> &nbsp;·&nbsp;
<a href="https://docs.cowagent.ai/">📖 文档中心</a> &nbsp;·&nbsp;
<a href="https://docs.cowagent.ai/guide/quick-start">🚀 快速开始</a> &nbsp;·&nbsp;
<a href="https://docs.cowagent.ai/zh/">📖 文档中心</a> &nbsp;·&nbsp;
<a href="https://docs.cowagent.ai/zh/guide/quick-start">🚀 快速开始</a> &nbsp;·&nbsp;
<a href="https://skills.cowagent.ai/">🧩 技能广场</a> &nbsp;·&nbsp;
<a href="https://link-ai.tech/cowagent/create">☁️ 在线体验</a>
</p>
@@ -25,15 +25,15 @@ CowAgent 轻量、易部署、可扩展，自由接入主流大模型，覆盖
| 能力 | 说明 |
| :--- | :--- |
| [任务规划](https://docs.cowagent.ai/intro/architecture) | 理解复杂任务并自主分解执行，循环调用工具直到完成目标 |
| [长期记忆](https://docs.cowagent.ai/memory) | 三层记忆架构（上下文 → 天级 → 核心），梦境蒸馏自动整理，支持关键词与向量混合检索 |
| [知识库](https://docs.cowagent.ai/knowledge) | 自动整理结构化知识为 Markdown Wiki，构建持续增长的知识图谱，可视化浏览 |
| [技能](https://docs.cowagent.ai/skills) | 从 [Skill Hub](https://skills.cowagent.ai/)、GitHub、ClawHub 等一键安装；也可通过对话创造自定义技能 |
| [工具](https://docs.cowagent.ai/tools) | 内置文件读写、终端、浏览器、定时任务、记忆检索、联网搜索等 10+ 工具，支持 MCP 协议 |
| [通道](https://docs.cowagent.ai/channels) | 一个 Agent 同时接入 Web、微信、飞书、钉钉、企微、QQ、公众号、Telegram、Slack 等多个渠道 |
| [任务规划](https://docs.cowagent.ai/zh/intro/architecture) | 理解复杂任务并自主分解执行，循环调用工具直到完成目标 |
| [长期记忆](https://docs.cowagent.ai/zh/memory) | 三层记忆架构（上下文 → 天级 → 核心），梦境蒸馏自动整理，支持关键词与向量混合检索 |
| [知识库](https://docs.cowagent.ai/zh/knowledge) | 自动整理结构化知识为 Markdown Wiki，构建持续增长的知识图谱，可视化浏览 |
| [技能](https://docs.cowagent.ai/zh/skills) | 从 [Skill Hub](https://skills.cowagent.ai/)、GitHub、ClawHub 等一键安装；也可通过对话创造自定义技能 |
| [工具](https://docs.cowagent.ai/zh/tools) | 内置文件读写、终端、浏览器、定时任务、记忆检索、联网搜索等 10+ 工具，支持 MCP 协议 |
| [通道](https://docs.cowagent.ai/zh/channels) | 一个 Agent 同时接入 Web、微信、飞书、钉钉、企微、QQ、公众号、Telegram、Slack 等多个渠道 |
| 多模态 | 文本、图片、语音、文件全消息类型支持，覆盖识别、生成、收发 |
| [模型](https://docs.cowagent.ai/models) | DeepSeek、Claude、Gemini、GPT、GLM、Qwen、Kimi、MiniMax、Doubao 等主流厂商，配置一行切换 |
| [部署](https://docs.cowagent.ai/guide/quick-start) | 一键脚本安装，Web 控制台统一管理；本地、Docker、服务器多种部署方式 |
| [模型](https://docs.cowagent.ai/zh/models) | DeepSeek、Claude、Gemini、GPT、GLM、Qwen、Kimi、MiniMax、Doubao 等主流厂商，配置一行切换 |
| [部署](https://docs.cowagent.ai/zh/guide/quick-start) | 一键脚本安装，Web 控制台统一管理；本地、Docker、服务器多种部署方式 |
<br/>
@@ -43,7 +43,7 @@ CowAgent 轻量、易部署、可扩展，自由接入主流大模型，覆盖
CowAgent 是一个完整的 **Agent Harness**：消息从各类**通道**进入，**Agent Core** 结合记忆、知识库与可用工具/技能进行任务规划与决策，调用**模型**生成结果，再回传至原通道。各模块解耦清晰，按需扩展。
详见 [项目架构](https://docs.cowagent.ai/intro/architecture)。
详见 [项目架构](https://docs.cowagent.ai/zh/intro/architecture)。
<br/>
@@ -74,9 +74,9 @@ docker compose up -d
> 服务器部署且需要公网访问控制台时，请在 `config.json` 中将 `web_host` 设为 `0.0.0.0`（同时强烈建议设置 `web_password` 启用鉴权），然后访问 `http://<server-ip>:9899`，并确保防火墙/安全组放行 `9899` 端口。
> 📖 详细安装指南：[快速开始](https://docs.cowagent.ai/guide/quick-start) · [源码安装](https://docs.cowagent.ai/guide/manual-install) · [升级](https://docs.cowagent.ai/guide/upgrade)
> 📖 详细安装指南：[快速开始](https://docs.cowagent.ai/zh/guide/quick-start) · [源码安装](https://docs.cowagent.ai/zh/guide/manual-install) · [升级](https://docs.cowagent.ai/zh/guide/upgrade)
安装后可使用 `cow` [CLI 命令](https://docs.cowagent.ai/cli) 管理服务：
安装后可使用 `cow` [CLI 命令](https://docs.cowagent.ai/zh/cli) 管理服务：
```bash
cow start | stop | restart # 服务管理
@@ -94,21 +94,21 @@ CowAgent 支持国内外主流厂商的大语言模型。**文本对话、图像
| 厂商 | 代表模型 | 文本 | 图像理解 | 图像生成 | 语音识别 | 语音合成 | 向量 |
| --- | --- | :-: | :-: | :-: | :-: | :-: | :-: |
| [DeepSeek](https://docs.cowagent.ai/models/deepseek) | deepseek-v4-flash / pro | ✅ | | | | | |
| [MiniMax](https://docs.cowagent.ai/models/minimax) | MiniMax-M2.7 | ✅ | ✅ | ✅ | | ✅ | |
| [Claude](https://docs.cowagent.ai/models/claude) | claude-opus-4-8 | ✅ | ✅ | | | | |
| [Gemini](https://docs.cowagent.ai/models/gemini) | gemini-3.5-flash | ✅ | ✅ | ✅ | | | |
| [OpenAI](https://docs.cowagent.ai/models/openai) | gpt-5.5、o 系列 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [智谱 GLM](https://docs.cowagent.ai/models/glm) | glm-5.1、glm-5v-turbo | ✅ | ✅ | | ✅ | | ✅ |
| [通义千问](https://docs.cowagent.ai/models/qwen) | qwen3.7-max | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [豆包 Doubao](https://docs.cowagent.ai/models/doubao) | doubao-seed-2.0 系列 | ✅ | ✅ | ✅ | | | ✅ |
| [Kimi](https://docs.cowagent.ai/models/kimi) | kimi-k2.6 | ✅ | ✅ | | | | |
| [百度ERNIE](https://docs.cowagent.ai/models/qianfan) | ernie-5.1 | ✅ | ✅ | | | | |
| [小米 MiMo](https://docs.cowagent.ai/models/mimo) | mimo-v2.5-pro / v2.5 | ✅ | ✅ | | | ✅ | |
| [LinkAI](https://docs.cowagent.ai/models/linkai) | 一个 Key 接入 100+ 模型 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [自定义](https://docs.cowagent.ai/models/custom) | 本地模型 / 三方代理 | ✅ | | | | | |
| [DeepSeek](https://docs.cowagent.ai/zh/models/deepseek) | deepseek-v4-flash / pro | ✅ | | | | | |
| [MiniMax](https://docs.cowagent.ai/zh/models/minimax) | MiniMax-M2.7 | ✅ | ✅ | ✅ | | ✅ | |
| [Claude](https://docs.cowagent.ai/zh/models/claude) | claude-opus-4-8 | ✅ | ✅ | | | | |
| [Gemini](https://docs.cowagent.ai/zh/models/gemini) | gemini-3.5-flash | ✅ | ✅ | ✅ | | | |
| [OpenAI](https://docs.cowagent.ai/zh/models/openai) | gpt-5.5、o 系列 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [智谱 GLM](https://docs.cowagent.ai/zh/models/glm) | glm-5.1、glm-5v-turbo | ✅ | ✅ | | ✅ | | ✅ |
| [通义千问](https://docs.cowagent.ai/zh/models/qwen) | qwen3.7-max | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [豆包 Doubao](https://docs.cowagent.ai/zh/models/doubao) | doubao-seed-2.0 系列 | ✅ | ✅ | ✅ | | | ✅ |
| [Kimi](https://docs.cowagent.ai/zh/models/kimi) | kimi-k2.6 | ✅ | ✅ | | | | |
| [百度ERNIE](https://docs.cowagent.ai/zh/models/qianfan) | ernie-5.1 | ✅ | ✅ | | | | |
| [小米 MiMo](https://docs.cowagent.ai/zh/models/mimo) | mimo-v2.5-pro / v2.5 | ✅ | ✅ | | | ✅ | |
| [LinkAI](https://docs.cowagent.ai/zh/models/linkai) | 一个 Key 接入 100+ 模型 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [自定义](https://docs.cowagent.ai/zh/models/custom) | 本地模型 / 三方代理 | ✅ | | | | | |
> 推荐通过 Web 控制台在线配置，无需手动编辑文件。手动配置请参考各厂商文档，详见 [模型概览](https://docs.cowagent.ai/models)。
> 推荐通过 Web 控制台在线配置，无需手动编辑文件。手动配置请参考各厂商文档，详见 [模型概览](https://docs.cowagent.ai/zh/models)。
<br/>
@@ -118,20 +118,20 @@ CowAgent 支持国内外主流厂商的大语言模型。**文本对话、图像
| 通道 | 文本 | 图片 | 文件 | 语音 | 群聊 |
| --- | :-: | :-: | :-: | :-: | :-: |
| [Web 控制台](https://docs.cowagent.ai/channels/web)（默认） | ✅ | ✅ | ✅ | ✅ | |
| [微信](https://docs.cowagent.ai/channels/weixin) | ✅ | ✅ | ✅ | ✅ | |
| [飞书](https://docs.cowagent.ai/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [钉钉](https://docs.cowagent.ai/channels/dingtalk) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [企微智能机器人](https://docs.cowagent.ai/channels/wecom-bot) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [QQ](https://docs.cowagent.ai/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
| [企业微信应用](https://docs.cowagent.ai/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
| [微信客服](https://docs.cowagent.ai/channels/wechat-kf) | ✅ | ✅ | ✅ | ✅ | |
| [微信公众号](https://docs.cowagent.ai/channels/wechatmp) | ✅ | ✅ | | ✅ | |
| [Telegram](https://docs.cowagent.ai/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Slack](https://docs.cowagent.ai/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
| [Discord](https://docs.cowagent.ai/channels/discord) | ✅ | ✅ | ✅ | | ✅ |
| [Web 控制台](https://docs.cowagent.ai/zh/channels/web)（默认） | ✅ | ✅ | ✅ | ✅ | |
| [微信](https://docs.cowagent.ai/zh/channels/weixin) | ✅ | ✅ | ✅ | ✅ | |
| [飞书](https://docs.cowagent.ai/zh/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [钉钉](https://docs.cowagent.ai/zh/channels/dingtalk) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [企微智能机器人](https://docs.cowagent.ai/zh/channels/wecom-bot) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [QQ](https://docs.cowagent.ai/zh/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
| [企业微信应用](https://docs.cowagent.ai/zh/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
| [微信客服](https://docs.cowagent.ai/zh/channels/wechat-kf) | ✅ | ✅ | ✅ | ✅ | |
| [微信公众号](https://docs.cowagent.ai/zh/channels/wechatmp) | ✅ | ✅ | | ✅ | |
| [Telegram](https://docs.cowagent.ai/zh/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Slack](https://docs.cowagent.ai/zh/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
| [Discord](https://docs.cowagent.ai/zh/channels/discord) | ✅ | ✅ | ✅ | | ✅ |
> 飞书、企微智能机器人支持在 Web 控制台内**扫码一键接入**，无需公网 IP。详见 [通道概览](https://docs.cowagent.ai/channels)。
> 飞书、企微智能机器人支持在 Web 控制台内**扫码一键接入**，无需公网 IP。详见 [通道概览](https://docs.cowagent.ai/zh/channels)。
<img src="https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/screenshots/zh/web-console-chat.png" alt="CowAgent Web 控制台" width="800"/>
@@ -141,9 +141,9 @@ CowAgent 支持国内外主流厂商的大语言模型。**文本对话、图像
## 🧠 记忆与知识库
**长期记忆**采用三层架构：对话上下文（短期）→ 天级记忆（中期）→ MEMORY.md（长期）。每日自动执行**梦境蒸馏（Deep Dream）**，将分散记忆整合为精炼的长期记忆并生成叙事日记。详见 [长期记忆](https://docs.cowagent.ai/memory) · [梦境蒸馏](https://docs.cowagent.ai/memory/deep-dream)。
**长期记忆**采用三层架构：对话上下文（短期）→ 天级记忆（中期）→ MEMORY.md（长期）。每日自动执行**梦境蒸馏（Deep Dream）**，将分散记忆整合为精炼的长期记忆并生成叙事日记。详见 [长期记忆](https://docs.cowagent.ai/zh/memory) · [梦境蒸馏](https://docs.cowagent.ai/zh/memory/deep-dream)。
**个人知识库** 与按时间记录的记忆不同，以**主题为维度**组织结构化知识。Agent 在对话中自动整理有价值信息，维护交叉引用与索引，Web 控制台可可视化浏览知识图谱。详见 [个人知识库](https://docs.cowagent.ai/knowledge)。
**个人知识库** 与按时间记录的记忆不同，以**主题为维度**组织结构化知识。Agent 在对话中自动整理有价值信息，维护交叉引用与索引，Web 控制台可可视化浏览知识图谱。详见 [个人知识库](https://docs.cowagent.ai/zh/knowledge)。
<table>
<tr>
@@ -171,7 +171,7 @@ CowAgent 支持国内外主流厂商的大语言模型。**文本对话、图像
**MCP 协议** 通过 [Model Context Protocol](https://modelcontextprotocol.io) 接入开放生态中的各种 MCP 服务，配置一次 `mcp.json` 即用即得，支持 stdio / SSE 协议、热更新、零代码接入。
详见 [工具概览](https://docs.cowagent.ai/tools) · [MCP 集成](https://docs.cowagent.ai/tools/mcp)。
详见 [工具概览](https://docs.cowagent.ai/zh/tools) · [MCP 集成](https://docs.cowagent.ai/zh/tools/mcp)。
### 技能系统
@@ -185,7 +185,7 @@ CowAgent 支持国内外主流厂商的大语言模型。**文本对话、图像
/skill install <名称> # 一键安装
```
详见 [技能概览](https://docs.cowagent.ai/skills) · [创建技能](https://docs.cowagent.ai/skills/create)。
详见 [技能概览](https://docs.cowagent.ai/zh/skills) · [创建技能](https://docs.cowagent.ai/zh/skills/create)。
<br/>
@@ -205,7 +205,7 @@ CowAgent 支持国内外主流厂商的大语言模型。**文本对话、图像
> **2026.02.03：** [v2.0.0](https://github.com/zhayujie/CowAgent/releases/tag/2.0.0) — 正式升级为超级 Agent 助理，支持多轮任务决策、长期记忆、Skills 框架
完整更新历史：[Release Notes](https://docs.cowagent.ai/releases)
完整更新历史：[Release Notes](https://docs.cowagent.ai/zh/releases)
<br/>

56
docs/zh/channels/dingtalk.mdx Normal file
View File

@@ -0,0 +1,56 @@
---
title: 钉钉
description: 将 CowAgent 接入钉钉应用
---
通过钉钉开放平台创建智能机器人应用，将 CowAgent 接入钉钉。
## 一、创建应用
1. 进入 [钉钉开发者后台](https://open-dev.dingtalk.com/fe/app#/corp/app)，登录后点击 **创建应用**，填写应用相关信息：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-create-app.png" width="800"/>
2. 点击添加应用能力，选择 **机器人** 能力，点击 **添加**：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-add-bot.png" width="800"/>
3. 配置机器人信息后点击 **发布**。发布后，点击 "**点击调试**"，会自动创建测试群聊，可在客户端查看：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-config-bot.png" width="600"/>
4. 点击 **版本管理与发布**，创建新版本发布：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-publish-bot.png" width="700"/>
## 二、项目配置
1. 点击 **凭证与基础信息**，获取 `Client ID` 和 `Client Secret`：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-get-secret.png" width="700"/>
2. 将以下配置加入项目根目录的 `config.json` 文件：
```json
{
"channel_type": "dingtalk",
"dingtalk_client_id": "YOUR_CLIENT_ID",
"dingtalk_client_secret": "YOUR_CLIENT_SECRET"
}
```
3. 安装依赖：
```bash
pip3 install dingtalk_stream
```
4. 启动项目后，在钉钉开发者后台点击 **事件订阅**，点击 **已完成接入，验证连接通道**，显示 **连接接入成功** 即表示配置完成：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-event-sub.png" width="700"/>
## 三、使用
与机器人私聊或将机器人拉入企业群中均可开启对话：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/dingtalk-hosting-demo.png" width="650"/>

93
docs/zh/channels/discord.mdx Normal file
View File

@@ -0,0 +1,93 @@
---
title: Discord
description: 将 CowAgent 接入 Discord Bot
---
> 通过 Discord Bot 的 **Gateway 长连接** 接入 CowAgent，支持私聊（DM）与服务器频道（@机器人 / 回复机器人触发）。Gateway 基于 WebSocket 长连接，无需公网 IP 与回调地址，开箱即用。
## 一、接入步骤
### 步骤一：创建 Discord 应用与 Bot
1. 打开 [Discord 开发者后台](https://discord.com/developers/applications)，点击 **New Application**，填写名称（如 `CowAgent`）并创建。
2. 左侧菜单进入 **Bot** 页面，点击 **Reset Token** 生成 Bot Token，复制并妥善保存（仅显示一次）。
<Tip>
这个 Token 等同于 Bot 的密码，请勿泄露。若意外泄漏，在 Bot 页面再次点击 **Reset Token** 重置即可。
</Tip>
### 步骤二：开启 Message Content Intent
私聊与频道读取文本均依赖该权限。
1. 在 **Bot** 页面下方找到 **Privileged Gateway Intents**。
2. 打开 **Message Content Intent** 开关并保存。
<Note>
未开启该开关时，机器人收到的消息内容会为空，导致无响应。
</Note>
### 步骤三：邀请 Bot 进入服务器
1. 左侧菜单进入 **OAuth2 → URL Generator**。
2. **Scopes** 勾选 `bot`。
3. **Bot Permissions** 至少勾选：`Send Messages`、`Read Message History`、`Attach Files`、`View Channels`。
4. 复制底部生成的授权链接，在浏览器打开，选择目标服务器完成授权。
<Note>
仅需私聊（DM）可跳过此步，但仍需先在任意共同服务器中与机器人建立 DM 通道，或由用户主动私聊机器人。
</Note>
### 步骤四：接入 CowAgent
<Tabs>
<Tab title="Web 控制台（推荐）">
打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **Discord**，填入 Bot Token，点击接入即可。
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动：
```json
{
"channel_type": "discord",
"discord_token": "your-discord-bot-token",
"discord_group_trigger": "mention_or_reply"
}
```
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `discord_token` | 开发者后台 Bot 页面生成的 Bot Token | - |
| `discord_group_trigger` | 频道触发方式：`mention_or_reply`（@或回复机器人）/ `mention_only`（仅@） / `all`（所有消息） | `mention_or_reply` |
</Tab>
</Tabs>
启动 Cow 后，日志中出现以下输出即表示接入成功：
```
[Discord] Bot logged in as CowAgent#1234 (id=123456789)
[Discord] ✅ Discord bot ready, listening for messages
```
## 二、功能说明
| 功能 | 支持情况 |
| --- | --- |
| 私聊（DM） | ✅ |
| 服务器频道（@机器人 / 回复机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发（PDF / Word / Excel 等） |
<Note>
Discord 单条消息上限为 2000 字符，超长回复会自动按换行拆分为多条发送。
</Note>
## 三、使用
完成接入后：
- **私聊（DM）**：在服务器成员列表中找到你的机器人，点击头像直接发消息对话。
- **频道**：在已邀请机器人的频道中，使用 `@你的机器人 你好` 或 **回复机器人的某条消息** 触发对话。
发送图片或文件时，可以在附件的输入框中 **添加文字说明**（描述/问题）一并发送，机器人会结合附件回答。也支持先发附件再发问题，两条消息会自动合并提问。

111
docs/zh/channels/feishu.mdx Normal file
View File

@@ -0,0 +1,111 @@
---
title: 飞书
description: 将 CowAgent 接入飞书应用
---
> 通过飞书自建应用接入 CowAgent，支持单聊与群聊（@机器人），使用 WebSocket 长连接模式，无需公网 IP，支持流式打字机回复、语音消息收发。
<Note>
接入需要是飞书企业用户且具有企业管理权限。
</Note>
## 一、接入方式
### 方式一：扫码一键接入（推荐）
启动 Cow 项目后在终端中即可完成扫码创建。或打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **飞书**，点击 **一键创建飞书应用**，使用 **飞书 App** 扫描二维码即可自动完成应用创建并接入:
<img src="https://cdn.link-ai.tech/doc/20260505181126.png" width="800"/>
<Note>
1. `lark-oapi` 依赖版本需要 >=1.5.5
2. 扫码创建出的应用会自动预置全部所需权限（消息收发、卡片读写、群聊事件等）和事件订阅，无需到开发者后台手动配置。
</Note>
### 方式二：手动创建接入
需要先在飞书开放平台创建自建应用并配置权限，再通过 Web 控制台或配置文件接入。
**步骤一：创建应用**
1. 进入 [飞书开发平台](https://open.feishu.cn/app/)，点击 **创建企业自建应用**：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-create-app.jpg" width="500"/>
2. 在 **添加应用能力** 中，为应用添加 **机器人** 能力：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-add-bot.jpg" width="800"/>
3. 在 **权限管理** 中，将以下权限粘贴到输入框，全选并 **批量开通**：
```
im:message,im:message.group_at_msg,im:message.group_at_msg:readonly,im:message.p2p_msg,im:message.p2p_msg:readonly,im:message:send_as_bot,im:resource,cardkit:card:write
```
<img src="https://cdn.link-ai.tech/doc/feishu-hosting-add-auth2.png" width="800"/>
4. 在 **凭证与基础信息** 中获取 `App ID` 和 `App Secret`：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/feishu-hosting-appid-secret.jpg" width="800"/>
**步骤二：接入 CowAgent**
<Tabs>
<Tab title="Web 控制台">
打开 Web 控制台，选择 **通道** 菜单，点击 **接入通道**，选择 **飞书**，切换到「手动填写」Tab，输入 App ID 和 App Secret，点击接入即可。
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动程序：
```json
{
"channel_type": "feishu",
"feishu_app_id": "YOUR_APP_ID",
"feishu_app_secret": "YOUR_APP_SECRET",
"feishu_stream_reply": true
}
```
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `feishu_app_id` | 飞书应用 App ID | - |
| `feishu_app_secret` | 飞书应用 App Secret | - |
| `feishu_stream_reply` | 是否开启流式打字机回复 | `true` |
</Tab>
</Tabs>
**步骤三：发布应用**
1. 启动 Cow 项目后，在飞书开放平台点击 **事件与回调**，选择 **长连接** 模式并保存：
<img src="https://cdn.link-ai.tech/doc/202601311731183.png" width="600"/>
2. 点击 **添加事件**，搜索 "接收消息"，选择 **接收消息 v2.0** 并确认。
3. 点击 **版本管理与发布**，创建版本并申请 **线上发布**，在飞书客户端审核通过：
<img src="https://cdn.link-ai.tech/doc/202601311807356.png" width="600"/>
## 二、功能说明
| 功能 | 支持情况 |
| --- | --- |
| 单聊 | ✅ |
| 群聊（@机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 语音消息 | ✅ 收发 |
| 流式回复 | ✅（通过 `feishu_stream_reply` 配置控制，默认开启） |
<Note>
流式回复需要机器人具备 `cardkit:card:write` 权限（一键创建已默认开通），且接收方飞书客户端版本 ≥ 7.20。低版本客户端会显示升级提示，权限或版本不满足时自动降级为普通文本回复。
</Note>
## 三、使用
完成接入后，在飞书中搜索机器人名称即可开始单聊对话。
如需在群聊中使用，将机器人添加到群中，@机器人发送消息即可。

45
docs/zh/channels/index.mdx Normal file
View File

@@ -0,0 +1,45 @@
---
title: 通道概览
description: CowAgent 支持的通道及能力矩阵
---
CowAgent 支持接入多种聊天通道，启动时通过 `channel_type` 切换。Web 控制台默认开启，可与其他接入通道并行运行。
## 能力矩阵
下表汇总各通道支持的入站消息类型、机器人回复类型与群聊能力，方便按场景选择。
| 通道 | 文本 | 图片 | 文件 | 语音 | 群聊 |
| --- | :-: | :-: | :-: | :-: | :-: |
| [微信](/zh/channels/weixin) | ✅ | ✅ | ✅ | ✅ | |
| [Web 控制台](/zh/channels/web) | ✅ | ✅ | ✅ | ✅ | |
| [飞书](/zh/channels/feishu) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [钉钉](/zh/channels/dingtalk) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [企微智能机器人](/zh/channels/wecom-bot) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [QQ](/zh/channels/qq) | ✅ | ✅ | ✅ | | ✅ |
| [企业微信应用](/zh/channels/wecom) | ✅ | ✅ | ✅ | ✅ | |
| [公众号](/zh/channels/wechatmp) | ✅ | ✅ | | ✅ | |
| [Telegram](/zh/channels/telegram) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Slack](/zh/channels/slack) | ✅ | ✅ | ✅ | | ✅ |
| [Discord](/zh/channels/discord) | ✅ | ✅ | ✅ | | ✅ |
- **图片 / 文件 / 语音**列表示通道支持收发对应消息类型，具体细节详见各通道文档
- **群聊**列指可识别并响应群消息
<Tip>
每个通道的语音 / 图像能力依赖对应模型厂商的配置，详见 [模型概览](/models)。
</Tip>
## 通道一览
- [Web 控制台](/zh/channels/web) — 内置浏览器对话和管理面板，默认开启
- [微信](/zh/channels/weixin) — 通过个人微信扫码登录
- [飞书](/zh/channels/feishu) — 飞书自建机器人
- [钉钉](/zh/channels/dingtalk) — 钉钉自建机器人
- [企微智能机器人](/zh/channels/wecom-bot) — 企业微信智能机器人
- [QQ](/zh/channels/qq) — QQ 官方机器人开放平台
- [企业微信应用](/zh/channels/wecom) — 企业微信自建应用接入
- [公众号](/zh/channels/wechatmp) — 微信公众号（订阅号 / 服务号）
- [Telegram](/zh/channels/telegram) — 海外 IM，5 分钟接入，无需公网 IP
- [Slack](/zh/channels/slack) — 团队协作 IM，Socket Mode 接入，无需公网 IP
- [Discord](/zh/channels/discord) — 社区 IM，Gateway 长连接接入，无需公网 IP

88
docs/zh/channels/qq.mdx Normal file
View File

@@ -0,0 +1,88 @@
---
title: QQ 机器人
description: 将 CowAgent 接入 QQ 机器人（WebSocket 长连接模式）
---
> 通过 QQ 开放平台的机器人接口接入 CowAgent，支持 QQ 单聊、QQ 群聊（@机器人）、频道消息和频道私信，无需公网 IP，使用 WebSocket 长连接模式。
<Note>
QQ 机器人通过 QQ 开放平台创建，使用 WebSocket 长连接接收消息，通过 OpenAPI 发送消息，无需公网 IP 和域名。
</Note>
## 一、创建 QQ 机器人
> 进入[QQ 开放平台](https://q.qq.com)，QQ扫码登录，如果未注册开放平台账号，请先完成[账号注册](https://q.qq.com/#/register)。
1.在 [QQ开放平台-机器人列表页](https://q.qq.com/#/apps)，点击创建机器人:
<img src="https://cdn.link-ai.tech/doc/20260317162900.png" width="800"/>
2.填写机器人名称、头像等基本信息，完成创建：
<img src="https://cdn.link-ai.tech/doc/20260317163005.png" width="800"/>
3.点击进入机器人配置页面，选择**开发管理**菜单，完成以下步骤：
- 复制并记录 **AppID**（机器人ID）
- 生成并记录 **AppSecret**（机器人秘钥）
<img src="https://cdn.link-ai.tech/doc/20260317164955.png" width="800"/>
## 二、配置和运行
### 方式一：Web 控制台接入
启动 Cow项目后打开 Web 控制台 (本地链接为: http://127.0.0.1:9899/ )，选择 **通道** 菜单，点击 **接入通道**，选择 **QQ 机器人**，填写上一步保存的 AppID 和 AppSecret，点击接入即可。
<img src="https://cdn.link-ai.tech/doc/20260317165425.png" width="800"/>
### 方式二：配置文件接入
在 `config.json` 中添加以下配置：
```json
{
"channel_type": "qq",
"qq_app_id": "YOUR_APP_ID",
"qq_app_secret": "YOUR_APP_SECRET"
}
```
| 参数 | 说明 |
| --- | --- |
| `qq_app_id` | QQ 机器人的 AppID，在开放平台开发管理中获取 |
| `qq_app_secret` | QQ 机器人的 AppSecret，在开放平台开发管理中获取 |
配置完成后启动程序，日志显示 `[QQ] ✅ Connected successfully` 即表示连接成功。
## 三、使用
在 QQ开放平台 - 管理 - **使用范围和人员** 菜单中，使用QQ客户端扫描 "添加到群和消息列表" 的二维码，即可开始与QQ机器人的聊天：
<img src="https://cdn.link-ai.tech/doc/20260317165947.png" width="800"/>
对话效果：
<img src="https://cdn.link-ai.tech/doc/20260317171508.png" width="800"/>
## 四、功能说明
> 注意：若需在群聊及频道中使用QQ机器人，需完成发布上架审核并在使用范围配置权限使用范围。
| 功能 | 支持情况 |
| --- | --- |
| QQ 单聊 | ✅ |
| QQ 群聊（@机器人） | ✅ |
| 频道消息（@机器人） | ✅ |
| 频道私信 | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发（群聊和单聊） |
| 文件消息 | ✅ 发送（群聊和单聊） |
| 定时任务 | ✅ 主动推送（每月每用户限 4 条） |
## 五、注意事项
- **被动消息限制**：QQ 单聊被动消息有效期为 60 分钟，每条消息最多回复 5 次；QQ 群聊被动消息有效期为 5 分钟。
- **主动消息限制**：单聊和群聊每月主动消息上限为 4 条，在使用定时任务功能时需要注意这个限制
- **事件权限**：默认订阅 `GROUP_AND_C2C_EVENT`（QQ群/单聊）和 `PUBLIC_GUILD_MESSAGES`（频道公域消息），如需其他事件类型请在开放平台申请权限。

118
docs/zh/channels/slack.mdx Normal file
View File

@@ -0,0 +1,118 @@
---
title: Slack
description: 将 CowAgent 接入 Slack App
---
> 通过 Slack App 的 **Socket Mode** 接入 CowAgent，支持私聊（DM）与频道（@机器人 / 线程内回复触发）。Socket Mode 基于长连接，无需公网 IP 与回调地址，开箱即用。
## 一、接入步骤
### 步骤一：创建 Slack App
1. 打开 [Slack API 应用管理页](https://api.slack.com/apps)，点击 **Create New App** → **From scratch**。
2. 填写 **App Name**（如 `CowAgent`），选择要安装的 **Workspace**，点击创建。
### 步骤二：开启 Socket Mode 并获取 App Token
1. 左侧菜单进入 **Settings → Socket Mode**，打开 **Enable Socket Mode**。
2. 系统会提示生成一个 **App-Level Token**，作用域勾选 `connections:write`，生成后保存这串以 `xapp-` 开头的 Token。
<Tip>
Socket Mode 通过 WebSocket 长连接接收事件，无需在公网暴露回调 URL，适合本地或内网部署。
</Tip>
### 步骤三：配置 Bot 权限并安装
1. 进入 **Features → OAuth & Permissions**，在 **Bot Token Scopes** 中点击 **Add an OAuth Scope**，逐项添加以下权限：
```
app_mentions:read
channels:history
chat:write
commands
files:read
files:write
groups:history
im:history
mpim:history
users:read
```
<Note>
`files:read` / `files:write` 用于图片、文件的收发；若仅需文本对话可省略。
</Note>
2. 进入 **Features → Event Subscriptions**，打开 **Enable Events**，在 **Subscribe to bot events** 中点击 **Add Bot User Event** 添加以下事件：
```
app_mention
message.im
message.channels
```
<Note>
如需在私有频道使用，再添加 `message.groups`。
</Note>
3. 进入 **Features → App Home**，在 **Show Tabs** 区域勾选 **Messages Tab**，并勾选下方的 **Allow users to send Slash commands and messages from the messages tab**（允许用户从消息标签页发送消息），否则私聊输入框会被关闭、无法给机器人发消息。
4. 回到 **OAuth & Permissions**，点击 **Install to Workspace** 完成安装，安装后获取以 `xoxb-` 开头的 **Bot User OAuth Token**。
<Tip>
若 Slack 客户端仍提示「向此应用发送消息的功能已关闭」，请确认已完成上一步的 App Home 设置，并刷新或重启 Slack 客户端（必要时把 App 从对话列表移除后重新打开）。
</Tip>
### 步骤四：接入 CowAgent
<Tabs>
<Tab title="Web 控制台（推荐）">
打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **Slack**，分别填入 Bot Token（`xoxb-`）和 App Token（`xapp-`），点击接入即可。
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动：
```json
{
"channel_type": "slack",
"slack_bot_token": "xoxb-xxxxxxxxxxxx",
"slack_app_token": "xapp-xxxxxxxxxxxx",
"slack_group_trigger": "mention_or_reply"
}
```
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `slack_bot_token` | Bot User OAuth Token，形如 `xoxb-...` | - |
| `slack_app_token` | App-Level Token（开启 Socket Mode 后生成），形如 `xapp-...` | - |
| `slack_group_trigger` | 频道触发方式：`mention_or_reply`（@或线程内回复）/ `mention_only`（仅@） / `all`（所有消息） | `mention_or_reply` |
</Tab>
</Tabs>
启动 Cow 后，日志中出现以下输出即表示接入成功：
```
[Slack] Bot logged in as user_id=U0XXXXXXX, team=Txxxxxxxx
[Slack] ✅ Slack bot ready, listening for events
```
## 二、功能说明
| 功能 | 支持情况 |
| --- | --- |
| 私聊（DM） | ✅ |
| 频道（@机器人 / 线程内回复） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发（PDF / Word / Excel 等） |
| 线程回复 | ✅ 回复发送至触发消息所在线程 |
<Note>
Slack 通过线程（Thread）组织对话。机器人会把回复发送到触发消息所在的线程，频道内更整洁。
</Note>
## 三、使用
完成接入后：
- **私聊（DM）**：在 Slack 左侧 **Apps** 中找到你的 App，直接发消息对话。
- **频道**：把 App 邀请进频道（`/invite @你的App`），使用 `@你的App 你好` 触发对话；后续在同一线程内直接回复即可继续对话。
发送图片或文件时，可以在附件的输入框中 **添加文字说明**（描述/问题）一并发送，机器人会结合附件回答。也支持先发附件再发问题，两条消息会自动合并提问。

112
docs/zh/channels/telegram.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: Telegram
description: 将 CowAgent 接入 Telegram Bot
---
> 通过 Telegram Bot API 接入 CowAgent，支持单聊与群聊（@机器人 / 回复机器人触发），使用 Long Polling 模式无需公网 IP，开箱即用。
## 一、接入步骤
### 步骤一：通过 BotFather 创建 Bot
1. 在 Telegram 中搜索并打开官方账号 [@BotFather](https://t.me/BotFather)。
2. 发送 `/newbot` 命令，按提示输入：
- **Bot 名称**（显示名，可中文，例如 `My CowAgent Bot`）
- **Bot 用户名**（必须以 `bot` 结尾，例如 `my_cowagent_bot`）
3. 创建成功后，BotFather 会返回一段 **HTTP API Token**（形如 `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`），妥善保存。
<Tip>
这个 Token 等同于 Bot 的密码，请勿泄露。如果意外泄漏可向 `@BotFather` 发送 `/revoke` 重置。
</Tip>
### 步骤二：（群聊使用）关闭 Privacy Mode
仅使用单聊可跳过此步。Telegram Bot 默认开启 **Privacy Mode**，群聊中只能收到带 `@bot` 的命令（如 `/start@your_bot`）以及对 bot 消息的 reply；**普通的 `@bot 你好` 文字消息收不到**，会导致群聊无响应。
向 `@BotFather` 发送：
1. `/setprivacy`
2. 选择刚才创建的 bot
3. 选择 `Disable`
<Note>
若设置后群聊仍无响应，可尝试把 Bot 从群里移除并重新拉入。
</Note>
### 步骤三：接入 CowAgent
<Tabs>
<Tab title="Web 控制台（推荐）">
打开 Web 控制台（本地链接：http://127.0.0.1:9899 ），选择 **通道** 菜单，点击 **接入通道**，选择 **Telegram**，填入 Bot Token，点击接入即可。
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动：
```json
{
"channel_type": "telegram",
"telegram_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
"telegram_group_trigger": "mention_or_reply"
}
```
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `telegram_token` | BotFather 返回的 HTTP API Token | - |
| `telegram_group_trigger` | 群聊触发方式：`mention_or_reply`（@或回复机器人）/ `mention_only`（仅@） / `all`（所有消息） | `mention_or_reply` |
| `telegram_register_commands` | 启动时是否自动向 BotFather 注册命令菜单 | `true` |
| `telegram_proxy` | （可选）代理地址，如 `http://127.0.0.1:7890`、`socks5://127.0.0.1:1080`；运行环境无法直连 `api.telegram.org` 时配置，留空则使用环境变量 `HTTPS_PROXY` | `""` |
</Tab>
</Tabs>
启动 Cow 后，日志中出现以下输出即表示接入成功：
```
[Telegram] Bot logged in as @my_cowagent_bot (id=123456789)
[Telegram] Registered 10 bot commands
[Telegram] ✅ Telegram bot ready, polling for updates
```
## 二、功能说明
| 功能 | 支持情况 |
| --- | --- |
| 单聊 | ✅ |
| 群聊（@机器人 / 回复机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 语音消息 | ✅ 收发（接收 OGG/Opus，发送 OGG/Opus） |
| 视频消息 | ✅ 收发 |
| 文件消息 | ✅ 收发（PDF / Word / Excel 等） |
| 命令菜单 | ✅ 与 Web 控制台 slash 命令一致 |
### 命令菜单
启动时会自动向 BotFather 注册命令菜单，用户在 Telegram 输入框输入 `/` 会出现下拉提示：
| 命令 | 说明 |
| --- | --- |
| `/help` | 显示命令帮助 |
| `/status` | 查看运行状态 |
| `/context` | 查看对话上下文（`/context clear` 清除） |
| `/skill` | 技能管理（`/skill list`、`/skill install` 等） |
| `/memory` | 记忆管理（`/memory dream`） |
| `/knowledge` | 知识库管理（`/knowledge list` / `on` / `off`） |
| `/config` | 查看当前配置 |
| `/cancel` | 中止当前正在运行的 Agent 任务 |
| `/logs` | 查看最近日志 |
| `/version` | 查看版本 |
<Note>
Telegram 命令菜单只能展示一级命令，子命令通过空格输入即可，例如 `/skill list`、`/context clear`。
</Note>
## 三、使用
完成接入后：
- **单聊**：在 Telegram 中搜索你创建的 Bot 用户名（如 `@my_cowagent_bot`），点击 `Start` 即可开始对话。
- **群聊**：把 Bot 拉进群，使用 `@bot 你好` 或 **回复 Bot 的某条消息** 触发对话。若群聊无响应，请检查 Privacy Mode 是否已按 [步骤二](#步骤二-群聊使用-关闭-privacy-mode) 关闭。
发送图片或文件时，可以直接在附件上方的输入框中 **添加 Caption**（描述/问题）一并发送，机器人会结合附件回答。也支持先发附件再发问题，两条消息会自动合并提问。

95
docs/zh/channels/web.mdx Normal file
View File

@@ -0,0 +1,95 @@
---
title: Web 控制台
description: 通过 Web 控制台使用 CowAgent
---
Web 控制台是 CowAgent 的默认通道，启动后会自动运行，通过浏览器即可与 Agent 对话，并支持在线管理模型、技能、记忆、通道等配置。
## 配置
```json
{
"channel_type": "web",
"web_host": "0.0.0.0",
"web_port": 9899,
"web_password": "",
"enable_thinking": false
}
```
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `channel_type` | 设为 `web` | `web` |
| `web_host` | Web 服务监听地址，默认监听 `127.0.0.1`（仅本机），如需公网访问请改为 `0.0.0.0` 并设置密码 | `""` |
| `web_port` | Web 服务监听端口 | `9899` |
| `web_password` | 访问密码，留空表示不启用密码保护；监听 `0.0.0.0` 时建议设置 | `""` |
| `web_session_expire_days` | 登录会话有效天数 | `30` |
| `web_file_serve_root` | web 端可直接读取/发送的文件根目录，默认仅限用户主目录及 agent 工作空间；设为 `/` 可放开整个文件系统 | `"~"` |
| `enable_thinking` | 是否启用深度思考模式 | `false` |
配置密码后，访问控制台时需先输入密码完成登录。登录状态默认保持 30 天，期间重启服务也无需重新登录。密码也支持在控制台的「配置」页面中在线修改。
## 访问地址
启动项目后访问：
- 本地运行：`http://localhost:9899`
- 服务器运行：`http://<server-ip>:9899`
<Note>
请确保服务器防火墙和安全组已放行对应端口。
</Note>
## 功能介绍
### 对话界面
支持流式输出，可实时展示 Agent 的思考过程（Reasoning）和工具调用过程（Tool Calls），更直观地观察 Agent 的决策过程。深度思考功能可通过配置或控制台的「Agent 配置」开关控制。
<img width="850" src="https://cdn.link-ai.tech/doc/20260227180120.png" />
#### 多会话管理
对话界面支持多会话（Session）管理，所有会话记录持久化存储在数据库中：
- **会话列表**：点击左侧历史会话图标可展开/收起会话列表面板，支持滚动加载全部历史会话
- **AI 生成标题**：新会话在首轮对话完成后，自动调用模型生成简短的会话摘要标题
- **新建会话**：点击会话列表顶部的「新对话」按钮或输入区的 `+` 按钮创建新会话
- **删除会话**：点击会话项的删除按钮，确认后永久删除该会话及其所有消息
- **清除上下文**：点击输入区的清除按钮，在当前会话中插入一条分隔线，分隔线以上的消息仍然展示但不再作为模型的上下文输入
### 模型管理
支持在线管理不同模型厂商的文本、图像、语音、向量模型配置，无需手动编辑配置文件：
<img width="850" src="https://cdn.link-ai.tech/doc/20260521212949.png" />
### 技能管理
支持在线查看和管理 Agent 技能（Skills）：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173403.png" />
### 记忆管理
支持在线查看和管理 Agent 记忆：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173349.png" />
### 通道管理
支持在线管理接入通道，支持实时连接/断开操作：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173331.png" />
### 定时任务
支持在线查看和管理定时任务，包括一次性任务、固定间隔、Cron 表达式等多种调度方式的可视化管理：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173704.png" />
### 日志
支持在线实时查看 Agent 运行日志，便于监控运行状态和排查问题：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173514.png" />

130
docs/zh/channels/wechat-kf.mdx Normal file
View File

@@ -0,0 +1,130 @@
---
title: 微信客服
description: 将 CowAgent 接入微信客服（WeCom Customer Service）
---
通过把企业微信自建应用绑定到「微信客服」账号，CowAgent 可以接管来自外部微信用户的客服咨询，并可在小程序、公众号、视频号及视频号小店等场景中通过链接或二维码触达微信用户。
<Note>
微信客服只能使用 Docker 部署或服务器 Python 部署，需要公网可达的回调地址，不支持本地运行模式。
</Note>
## 一、准备
需要的资源：
1. 一台服务器（有公网 IP）
2. 注册并已认证的企业微信
3. 已开通「微信客服」能力
<Note>
建议**单独再创建一个企微自建应用**用于微信客服，不要复用已有的 `wechatcom_app` 应用，否则两个通道会争抢同一个回调地址。
</Note>
## 二、创建企业微信自建应用
1. 在 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps)，点击 **应用管理 → 创建应用**：
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
2. 点击 **我的企业**，在最下方获取 **企业ID**（后续填写到 `wechat_kf_corp_id`）：
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-companyid.png" width="600"/>
3. 进入上一步创建的应用，点击 Secret 旁的「**查看**」，Secret 会推送到管理员手机端的企业微信里查看：
<img src="https://cdn.link-ai.tech/doc/wechatcom-hosting-agent-secret.png" width="600"/>
4. 进入应用 **接收消息 → 设置API接收**，点击右侧「**随机获取**」生成 **Token** 和 **EncodingAESKey** 并保存：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wechatcom-hosting-token-aeskey.jpg" width="600"/>
<Note>
此时保存 API 接收配置会失败，因为程序还未启动，等项目运行后再回来保存。
</Note>
## 三、配置和运行
填入上一步收集到的 4 个字段（Corp ID / Secret / Token / EncodingAESKey）：
<Tabs>
<Tab title="Web 控制台">
启动 Cow 项目后打开 Web 控制台，选择 **通道** 菜单，点击 **接入通道**，选择 **微信客服**，依次填入 Corp ID / Secret / Token / AES Key（端口默认 9888，可改），点击接入即可。
<img src="https://cdn.link-ai.tech/doc/cow-weixinkefu-web-control.png" width="800"/>
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置（各参数与企业微信后台的对应关系见上方截图）：
```json
{
"channel_type": "wechat_kf",
"wechat_kf_corp_id": "YOUR_CORP_ID",
"wechat_kf_secret": "YOUR_SECRET",
"wechat_kf_token": "YOUR_TOKEN",
"wechat_kf_aes_key": "YOUR_AES_KEY",
"wechat_kf_port": 9888
}
```
| 参数 | 说明 |
| --- | --- |
| `wechat_kf_corp_id` | 企业 ID |
| `wechat_kf_secret` | 绑定到微信客服的那个企微自建应用的 Secret |
| `wechat_kf_token` | API 接收配置中的 Token |
| `wechat_kf_aes_key` | API 接收配置中的 EncodingAESKey |
| `wechat_kf_port` | 监听端口，默认 9888 |
</Tab>
</Tabs>
接入完成后启动程序（Web 控制台方式会自动重启），日志中出现 `Listening on http://0.0.0.0:9888/wxkf/` 表示运行成功，需要将该端口对外开放（如在云服务器安全组中放行）。
接着回到企业微信「接收消息 → 设置API接收」，将回调 URL 填为 `http://<your-host>:9888/wxkf/`，点击保存。保存成功后还需将服务器 IP 添加到 **企业可信IP** 中，否则无法收发消息：
<img src="https://cdn.link-ai.tech/doc/wechat-com_config.png" width="600"/>
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
<Warning>
如遇到 URL 配置回调不通过或配置失败：
1. 确保服务器防火墙关闭且安全组放行监听端口（默认 9888）
2. 仔细检查 Token、Secret、EncodingAESKey 等参数配置是否一致，URL 格式是否正确
3. 认证企业微信需要配置与主体一致的备案域名
</Warning>
## 四、绑定微信客服账号
进入企业微信管理后台 **微信客服** 页面，创建客服账号并与上一步的企微自建应用绑定：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step1.jpg" width="600"/>
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step2.jpg" width="600"/>
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-step3.jpg" width="600"/>
绑定完成后，进入 **微信客服 → 微信客服账号详情**，在「**接入链接**」一栏：
- 点击「**复制链接**」可获得形如 `https://work.weixin.qq.com/kfid/kfcd83e5896b9ba07be` 的访问链接
- 点击「**生成二维码**」可获得对应的二维码
把链接或二维码推给微信客户使用即可：
<img src="https://cdn.link-ai.tech/doc/wechat-customer-service_use.png" width="600"/>
## 五、使用
微信用户通过链接或二维码进入客服对话后，即可与 AI 进行多轮对话，支持文本、图片、语音等消息：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-chat-demo.jpg" width="900"/>
除此之外，基于微信生态官方能力，还可将微信客服应用在公众号、小程序、视频号及视频号小店等场景，详情可查看企业微信管理后台 [微信客服 → 接入场景](https://work.weixin.qq.com/wework_admin/frame#/app/servicer) 的相关说明：
<img src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/wxcustomer-hosting-interface-demo.png" width="800"/>
## 常见问题
需要确保已安装以下依赖：
```bash
pip install websocket-client pycryptodome
```

72
docs/zh/channels/wechatmp.mdx Normal file
View File

@@ -0,0 +1,72 @@
---
title: 微信公众号
description: 将 CowAgent 接入微信公众号
---
CowAgent 支持接入个人订阅号和企业服务号两种公众号类型。
| 类型 | 要求 | 特点 |
| --- | --- | --- |
| **个人订阅号** | 个人可申请 | 收到消息时会回复一条提示，回复生成后需用户主动发消息获取 |
| **企业服务号** | 企业申请，需通过微信认证开通客服接口 | 回复生成后可主动推送给用户 |
<Note>
公众号仅支持服务器和 Docker 部署，不支持本地运行。需额外安装扩展依赖：`pip3 install -r requirements-optional.txt`
</Note>
## 一、个人订阅号
在 `config.json` 中添加以下配置：
```json
{
"channel_type": "wechatmp",
"single_chat_prefix": [""],
"wechatmp_app_id": "wx73f9******d1e48",
"wechatmp_app_secret": "YOUR_APP_SECRET",
"wechatmp_aes_key": "",
"wechatmp_token": "YOUR_TOKEN",
"wechatmp_port": 80
}
```
### 配置步骤
这些配置需要和 [微信公众号后台](https://mp.weixin.qq.com/advanced/advanced?action=dev&t=advanced/dev) 中的保持一致，进入页面后，在左侧菜单选择 **设置与开发 → 基本配置 → 服务器配置**，按下图进行配置：
<img src="https://cdn.link-ai.tech/doc/20260228103506.png" width="480"/>
1. 在公众平台启用开发者密码（对应配置 `wechatmp_app_secret`），并将服务器 IP 填入白名单
2. 按上图填写 `config.json` 中与公众号相关的配置，要与公众号后台的配置一致
3. 启动程序，启动后会监听 80 端口（若无权限监听，则在启动命令前加上 `sudo`；若 80 端口已被占用，则关闭该占用进程）
4. 在公众号后台 **启用服务器配置** 并提交，保存成功则表示已成功配置。注意 **"服务器地址(URL)"** 需要配置为 `http://{HOST}/wx` 的格式，其中 `{HOST}` 可以是服务器的 IP 或域名
随后关注公众号并发送消息即可看到以下效果：
<img src="https://cdn.link-ai.tech/doc/20260228103522.png" width="720"/>
由于受订阅号限制，回复内容较短的情况下（15s 内），可以立即完成回复，但耗时较长的回复则会先回复一句 "正在思考中"，后续需要用户输入任意文字主动获取答案，而服务号则可以通过客服接口解决这一问题。
<Tip>
**语音识别**：可利用微信自带的语音识别功能，需要在公众号管理页面的 "设置与开发 → 接口权限" 页面开启 "接收语音识别结果"。
</Tip>
## 二、企业服务号
企业服务号与上述个人订阅号的接入过程基本相同，差异如下：
1. 在公众平台申请企业服务号并完成微信认证，在接口权限中确认已获得 **客服接口** 的权限
2. 在 `config.json` 中设置 `"channel_type": "wechatmp_service"`，其他配置与上述订阅号相同
3. 交互效果上，即使是较长耗时的回复，也可以主动推送给用户，无需用户手动获取
```json
{
"channel_type": "wechatmp_service",
"single_chat_prefix": [""],
"wechatmp_app_id": "YOUR_APP_ID",
"wechatmp_app_secret": "YOUR_APP_SECRET",
"wechatmp_aes_key": "",
"wechatmp_token": "YOUR_TOKEN",
"wechatmp_port": 80
}
```

90
docs/zh/channels/wecom-bot.mdx Normal file
View File

@@ -0,0 +1,90 @@
---
title: 企微智能机器人
description: 将 CowAgent 接入企业微信智能机器人（长连接模式）
---
> 通过企业微信智能机器人接入CowAgent，支持企业内部单聊和内部群聊，无需公网 IP，使用 WebSocket 长连接模式，支持Markdown渲染和流式输出。
<Note>
智能机器人与企业微信自建应用是两种不同的接入方式。智能机器人使用 WebSocket 长连接，无需服务器公网 IP 和域名，配置更简单。
</Note>
## 一、接入方式
### 方式一：扫码一键接入（推荐）
无需提前创建机器人，启动 Cow 项目后打开 Web 控制台（本地链接：http://127.0.0.1:9899/），选择 **通道** 菜单，点击**接入通道**，选择**企微智能机器人**，切换到「扫码接入」模式，使用**企业微信**扫码即可自动完成机器人创建和接入。
<img src="https://cdn.link-ai.tech/doc/20260401121213.png" width="800"/>
<Note>
扫码成功后，可在企业微信工作台 - **智能机器人**页面对机器人进行进一步配置，包括修改名称、头像、可见范围等。
</Note>
### 方式二：手动创建接入
需要先在企业微信中创建智能机器人并获取 Bot ID 和 Secret，再通过 Web 控制台或配置文件接入。
**步骤一：创建智能机器人**
1. 打开企业微信客户端，进入工作台，点击**智能机器人**：
<img src="https://cdn.link-ai.tech/doc/20260316180959.png" width="800"/>
2. 点击创建机器人 - 手动创建：
<img src="https://cdn.link-ai.tech/doc/20260316181118.png" width="800"/>
3. 右侧窗口拖到最下方，选择**API模式创建**：
<img src="https://cdn.link-ai.tech/doc/20260316181215.png" width="800"/>
4. 设置机器人名称、头像、可见范围，并选择**长连接模式**，记录下 **Bot ID** 和 **Secret** 信息后点击保存。
**步骤二：接入 CowAgent**
<Tabs>
<Tab title="Web 控制台">
打开 Web 控制台，选择**通道**菜单，点击**接入通道**，选择**企微智能机器人**，切换到「手动填写」模式，输入 Bot ID 和 Secret，点击接入即可。
<img src="https://cdn.link-ai.tech/doc/20260316181711.png" width="800"/>
</Tab>
<Tab title="配置文件">
在 `config.json` 中添加以下配置后启动程序：
```json
{
"channel_type": "wecom_bot",
"wecom_bot_id": "YOUR_BOT_ID",
"wecom_bot_secret": "YOUR_SECRET"
}
```
| 参数 | 说明 |
| --- | --- |
| `wecom_bot_id` | 智能机器人的 BotID |
| `wecom_bot_secret` | 智能机器人的 Secret |
</Tab>
</Tabs>
日志显示 `[WecomBot] Subscribe success` 即表示连接成功。
## 二、功能说明
| 功能 | 支持情况 |
| --- | --- |
| 单聊 | ✅ |
| 群聊（@机器人） | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发 |
| 流式回复 | ✅ |
| 定时任务主动推送 | ✅ |
## 三、使用
在企业微信中搜索创建的机器人名称，即可开始单聊对话。
如需在企微内部群聊中使用，将机器人添加到群中，@机器人发送消息即可。
<img src="https://cdn.link-ai.tech/doc/20260316182902.png" width="800"/>

98
docs/zh/channels/wecom.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: 企微自建应用
description: 将 CowAgent 接入企业微信自建应用
---
通过企业微信自建应用接入 CowAgent，支持企业内部人员单聊使用。
<Note>
企业微信只能使用 Docker 部署或服务器 Python 部署，不支持本地运行模式。
</Note>
## 一、准备
需要的资源：
1. 一台服务器（有公网 IP）
2. 注册一个企业微信（个人也可注册，但无法认证）
3. 认证企业微信还需要对应主体备案的域名
## 二、创建企业微信应用
1. 在 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#profile) 点击 **我的企业**，在最下方获取 **企业ID**（后续填写到 `wechatcom_corp_id` 字段中）。
2. 切换到 **应用管理**，点击创建应用：
<img src="https://cdn.link-ai.tech/doc/20260228103156.png" width="480"/>
3. 进入应用创建页面，记录 `AgentId` 和 `Secret`：
<img src="https://cdn.link-ai.tech/doc/20260228103218.png" width="580"/>
4. 点击 **设置API接收**，配置应用接口：
<img src="https://cdn.link-ai.tech/doc/20260228103211.png" width="520"/>
- URL 格式为 `http://ip:port/wxcomapp`（认证企业需使用备案域名）
- 随机获取 `Token` 和 `EncodingAESKey` 并保存
<Note>
此时保存 API 接收配置会失败，因为程序还未启动，等项目运行后再回来保存。
</Note>
## 三、配置和运行
在 `config.json` 中添加以下配置（各参数与企业微信后台的对应关系见上方截图）：
```json
{
"channel_type": "wechatcom_app",
"single_chat_prefix": [""],
"wechatcom_corp_id": "YOUR_CORP_ID",
"wechatcomapp_token": "YOUR_TOKEN",
"wechatcomapp_secret": "YOUR_SECRET",
"wechatcomapp_agent_id": "YOUR_AGENT_ID",
"wechatcomapp_aes_key": "YOUR_AES_KEY",
"wechatcomapp_port": 9898
}
```
| 参数 | 说明 |
| --- | --- |
| `wechatcom_corp_id` | 企业 ID |
| `wechatcomapp_token` | API 接收配置中的 Token |
| `wechatcomapp_secret` | 应用的 Secret |
| `wechatcomapp_agent_id` | 应用的 AgentId |
| `wechatcomapp_aes_key` | API 接收配置中的 EncodingAESKey |
| `wechatcomapp_port` | 监听端口，默认 9898 |
配置完成后启动程序。当后台日志显示 `http://0.0.0.0:9898/` 时说明程序运行成功，需要将该端口对外开放（如在云服务器安全组中放行）。
程序启动后，回到企业微信后台保存 **消息服务器配置**，保存成功后还需将服务器 IP 添加到 **企业可信IP** 中，否则无法收发消息：
<img src="https://cdn.link-ai.tech/doc/20260228103224.png" width="520"/>
<Warning>
如遇到 URL 配置回调不通过或配置失败：
1. 确保服务器防火墙关闭且安全组放行监听端口
2. 仔细检查 Token、Secret Key 等参数配置是否一致，URL 格式是否正确
3. 认证企业微信需要配置与主体一致的备案域名
</Warning>
## 四、使用
在企业微信中搜索刚创建的应用名称，即可直接对话：
<img src="https://cdn.link-ai.tech/doc/20260228103228.png" width="720"/>
如需让外部个人微信用户使用，可在 **我的企业 → 微信插件** 中分享邀请关注二维码，个人微信扫码关注后即可与应用对话：
<img src="https://cdn.link-ai.tech/doc/20260228103232.png" width="520"/>
## 常见问题
需要确保已安装以下依赖：
```bash
pip install websocket-client pycryptodome
```

74
docs/zh/channels/weixin.mdx Normal file
View File

@@ -0,0 +1,74 @@
---
title: 微信
description: 将 CowAgent 接入个人微信（基于官方接口）
---
> 接入个人微信，扫码登录即可使用，支持文本、图片、语音、文件、视频等消息的私聊收发。通过微信官方API进行接入，无安全风险，接入后会在会话中新增一个机器人助手，不影响当前账号的使用。
## 一、配置和运行
### 方式一：Web 控制台接入
启动 Cow 项目后打开 Web 控制台 (本地链接为: http://127.0.0.1:9899/ )，选择 **通道** 菜单，点击 **接入通道**，选择 **微信**，点击接入后按照提示扫码登录。
<img src="https://cdn.link-ai.tech/doc/20260322195114.png" width="800" />
### 方式二：配置文件接入
在 `config.json` 中设置 `channel_type` 为 `weixin`：
```json
{
"channel_type": "weixin"
}
```
启动程序后，终端会显示二维码，使用微信扫码授权即可完成登录。
<img src="https://cdn.link-ai.tech/doc/20260322195509.png" width="800" />
<Note>
1. 兼容历史配置：`channel_type` 设为 `wx` 同样可以启用微信通道。
2. 注意微信客户端需要更新至 8.0.69 版本或以上
</Note>
## 二、使用说明
微信扫码并进行授权确认后，即可完成接入并开始对话。接入微信后会在对话中创建出一个机器人助理，不会对已有账号的正常使用有任何影响。
> 你可以通过搜索"微信ClawBot"随时找到这个机器人，还可以修改这个机器人的头像、备注等信息，将机器人置顶在消息列表等。
<img src="https://cdn.link-ai.tech/doc/83ae8251d896219fde4803f4205205be.jpg" width="250" />
## 三、登录说明
### 扫码登录
首次启动时，终端会显示一个二维码（有效期约 2 分钟）。使用微信扫描二维码并在手机上确认后即可完成登录。
- 二维码过期后会自动刷新并重新显示
- `requirements.txt` 中已默认包含 `qrcode` 依赖，安装后可在终端直接渲染二维码图案
### 凭证保存
登录成功后，凭证会自动保存至 `~/.weixin_cow_credentials.json`，下次启动时无需重新扫码。
如需重新登录，删除该凭证文件后重启程序即可。
### Session 过期
当微信 session 过期时（errcode -14），程序会自动清除旧凭证并重新发起扫码登录，无需手动干预。
## 四、功能说明
| 功能 | 支持情况 |
| --- | --- |
| 单聊 | ✅ |
| 文本消息 | ✅ 收发 |
| 图片消息 | ✅ 收发 |
| 文件消息 | ✅ 收发 |
| 视频消息 | ✅ 收发 |
| 语音消息 | ✅ 接收 (自带语音识别) |

124
docs/zh/cli/general.mdx Normal file
View File

@@ -0,0 +1,124 @@
---
title: 常用命令
description: 查看状态、管理配置和上下文等常用命令
---
以下命令支持在对话中使用 `/` 前缀，也支持在终端中使用 `cow` 前缀（部分命令仅对话可用）。
<Tip>
在 Web 控制台中输入 `/` 会自动弹出命令提示，支持键盘上下选择和 Tab 补全。
</Tip>
## help
显示所有可用命令的帮助信息。
```text
/help
```
## status
查看当前会话和服务的运行状态，包括进程信息、模型配置、会话消息数量和已加载技能数量。
```text
/status
```
输出示例：
```
🐮 CowAgent Status
Process: PID 12345 | Running 2h 15m
Version: 2.0.4
Channel: web
Model: MiniMax-M2.5
Mode: agent
Session: 12 messages | 8 skills loaded
```
## cancel
中止当前会话正在运行的 Agent 任务。在 Agent 执行长时间任务（例如多轮工具调用、长流式输出）时，可随时发送 `/cancel`，Agent 会在下一次工具执行前停止。Web 端、微信、企业微信、飞书等各通道均可使用。
```text
/cancel
```
## config
查看或修改运行时配置。修改后立即生效，无需重启服务。
**查看所有可配置项：**
```text
/config
```
**查看单个配置项：**
```text
/config model
```
**修改配置项：**
```text
/config model deepseek-v4-flash
```
**支持修改的配置项：**
| 配置项 | 说明 | 示例值 |
| --- | --- | --- |
| `model` | AI 模型名称 | `deepseek-v4-flash` |
| `agent_max_context_tokens` | 最大上下文 tokens | `40000` |
| `agent_max_context_turns` | 最大上下文记忆轮次 | `30` |
| `agent_max_steps` | 单次任务最大决策步数 | `15` |
| `enable_thinking` | 是否启用深度思考模式 | `true` / `false` |
<Note>
修改 `model` 时，系统会自动匹配对应的模型调用方式。配置会写入 `config.json` 并持久保存。
</Note>
## context
查看当前会话的上下文信息，包括消息数量、内容长度等统计。
```text
/context
```
**清空当前会话上下文：**
```text
/context clear
```
<Tip>
清空上下文后，Agent 会"忘记"之前的对话内容，适用于切换话题或释放上下文空间。
</Tip>
## logs
查看最近的服务日志，默认显示最近 20 行，最多 50 行。
```text
/logs
```
**指定行数：**
```text
/logs 50
```
## version
显示当前 CowAgent 版本号。
```text
/version
```

98
docs/zh/cli/index.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: 命令总览
description: CowAgent 命令系统 — 终端 CLI 和对话命令
---
CowAgent 提供两种命令交互方式：
- **终端CLI** — 在系统终端中执行 `cow <命令>`，用于服务管理、技能管理等运维操作
- **对话命令** — 在对话中输入 `/<命令>` 或 `cow <命令>`，用于查看状态、管理技能、调整配置等
## 终端命令
通过一键安装脚本部署后，`cow` 命令会自动可用。手动安装的用户需要在项目根目录下额外执行：
```bash
pip install -e .
```
安装后即可在任意位置使用 `cow` 命令：
```bash
cow help
```
输出示例：
```
CowAgent CLI
Usage: cow <command>
Service:
start Start the CowAgent service
stop Stop the CowAgent service
restart Restart the CowAgent service
update Update code and restart service
status Show service status
logs View service logs
Skills:
skill Manage skills (list / search / install / uninstall ...)
Memory & Knowledge:
memory Memory distillation (dream)
knowledge View knowledge base stats and structure
Others:
help Show this help message
version Show version
```
## 对话命令
在 Web 控制台或任意接入渠道的对话中，支持输入以 `/` 开头的命令：
| 命令 | 说明 |
| --- | --- |
| `/help` | 显示命令帮助 |
| `/status` | 查看服务状态和配置 |
| `/cancel` | 中止当前正在运行的 Agent 任务 |
| `/config` | 查看或修改运行时配置 |
| `/skill` | 管理技能（安装、卸载、启用、禁用等） |
| `/memory dream [N]` | 手动触发记忆蒸馏（默认 3 天，最大 30） |
| `/knowledge` | 查看知识库统计信息 |
| `/knowledge list` | 查看知识库目录结构 |
| `/knowledge on\|off` | 开启或关闭知识库 |
| `/context` | 查看当前会话上下文信息 |
| `/context clear` | 清空当前会话上下文 |
| `/logs` | 查看最近日志 |
| `/version` | 显示版本号 |
<Tip>
对话命令中 `/start`、`/stop`、`/restart` 等服务管理命令会提示到终端中执行，因为它们涉及进程操作。
</Tip>
## 命令对照表
以下是各命令在终端和对话中的可用性：
| 命令 | 终端 (`cow`) | 对话 (`/`) |
| --- | :---: | :---: |
| help | ✓ | ✓ |
| version | ✓ | ✓ |
| status | ✓ | ✓ |
| logs | ✓ | ✓ |
| cancel | ✗ | ✓ |
| config | ✗ | ✓ |
| context | — | ✓ |
| memory (子命令) | ✗ | ✓ |
| knowledge (子命令) | ✓ | ✓ |
| skill (子命令) | ✓ | ✓ |
| start / stop / restart | ✓ | ✗ |
| update | ✓ | ✗ |
| install-browser | ✓ | ✗ |
<Note>
`context` 在终端中仅提示到对话中使用。`config` 仅支持在对话中修改。
</Note>

77
docs/zh/cli/memory-knowledge.mdx Normal file
View File

@@ -0,0 +1,77 @@
---
title: 记忆与知识库
description: 记忆蒸馏和知识库管理命令
---
## memory
管理 Agent 的长期记忆系统。
### memory dream
手动触发记忆蒸馏（Deep Dream），整理近期的天级记忆，蒸馏合并到 MEMORY.md，并生成梦境日记。
```text
/memory dream [N]
```
- `N`：整理近 N 天的记忆，默认 3 天，最大 30 天
- 蒸馏在后台异步执行，完成后会在对话中通知结果
- 无需等待 Agent 初始化，首次对话前即可使用
**示例：**
```text
/memory dream # 整理近 3 天
/memory dream 7 # 整理近 7 天
/memory dream 30 # 整理近 30 天（全量）
```
蒸馏完成后，Web 端会收到带有跳转链接的通知，可直接查看更新后的 MEMORY.md 和梦境日记。
<Tip>
系统每天 23:55 会自动执行一次蒸馏（lookback 1 天）。手动触发适用于首次部署后的历史整理，或需要立即更新记忆时使用。
</Tip>
## knowledge
查看和管理个人知识库。默认显示知识库统计信息。
```text
/knowledge
```
输出示例：
```
📚 知识库
- 状态：已开启
- 页面数：12
- 总大小：45.2 KB
- 分类明细：
- concepts/: 5 篇
- entities/: 4 篇
- sources/: 3 篇
```
### knowledge list
查看知识库目录树结构。
```text
/knowledge list
```
### knowledge on / off
开启或关闭知识库。关闭后不再注入知识提示词和索引知识文件。
```text
/knowledge on
/knowledge off
```
<Note>
终端 CLI 中 `cow knowledge` 和 `cow knowledge list` 可用，但 `on|off` 仅支持在对话中使用（需实时生效）。
</Note>

134
docs/zh/cli/process.mdx Normal file
View File

@@ -0,0 +1,134 @@
---
title: 进程管理
description: 使用 cow 命令管理 CowAgent 进程的启动、停止、重启、更新等操作
---
进程管理命令用于控制 CowAgent 后台进程的生命周期。这些命令仅在终端中可用。
## start
启动 CowAgent 服务。默认以后台进程方式运行，并自动跟踪日志输出。
```bash
cow start
```
**选项：**
| 选项 | 说明 |
| --- | --- |
| `-f`, `--foreground` | 前台运行，不以后台守护进程方式启动 |
| `--no-logs` | 启动后不自动跟踪日志 |
## stop
停止正在运行的 CowAgent 服务。
```bash
cow stop
```
## restart
重启 CowAgent 服务（先停止再启动）。
```bash
cow restart
```
**选项：**
| 选项 | 说明 |
| --- | --- |
| `--no-logs` | 重启后不自动跟踪日志 |
## update
更新代码并重启服务。自动执行以下流程：
1. 拉取最新代码（`git pull`）
2. 停止当前服务
3. 更新 Python 依赖
4. 重新安装 CLI
5. 启动服务
```bash
cow update
```
<Warning>
如果 `git pull` 失败（如存在本地未提交的修改），更新会中止，服务不受影响。
</Warning>
## status
查看 CowAgent 服务运行状态，包括进程信息、版本号、当前配置的模型和通道。
```bash
cow status
```
输出示例：
```
🐮 CowAgent Status
Status: ● Running (PID: 12345)
Version: 2.0.4
Channel: web
Model: MiniMax-M2.5
Mode: agent
```
## logs
查看服务日志。
```bash
cow logs
```
**选项：**
| 选项 | 说明 | 默认值 |
| --- | --- | --- |
| `-f`, `--follow` | 持续跟踪日志输出 | 否 |
| `-n`, `--lines` | 显示最近 N 行 | 50 |
示例：
```bash
# 查看最近 100 行日志
cow logs -n 100
# 持续跟踪日志
cow logs -f
```
## install-browser
安装 Playwright 和 Chromium 浏览器，用于启用 [浏览器工具](/zh/tools/browser)。
```bash
cow install-browser
```
<Tip>
仅在需要使用浏览器工具（如网页浏览、截图等）时才需要安装。
</Tip>
## run.sh 兼容
如果未安装 Cow CLI，也可以使用 `run.sh` 脚本管理服务：
| cow 命令 | run.sh 等效命令 |
| --- | --- |
| `cow start` | `./run.sh start` |
| `cow stop` | `./run.sh stop` |
| `cow restart` | `./run.sh restart` |
| `cow update` | `./run.sh update` |
| `cow status` | `./run.sh status` |
| `cow logs` | `./run.sh logs` |
<Note>
推荐使用 `cow` 命令，它提供更简洁的语法和更丰富的功能。通过一键安装脚本部署时 `cow` 命令会自动安装。
</Note>

218
docs/zh/cli/skill.mdx Normal file
View File

@@ -0,0 +1,218 @@
---
title: 技能管理
description: 通过命令安装、卸载、启用、禁用和管理技能
---
技能管理命令用于安装、查询和管理 CowAgent 的技能。在对话中使用 `/skill <子命令>`，在终端中使用 `cow skill <子命令>`。
## list
列出已安装的技能及其状态。
<CodeGroup>
```text 对话
/skill list
```
```bash 终端
cow skill list
```
</CodeGroup>
输出示例：
```
📦 已安装的技能 (3/4)
✅ pptx
Use this skill any time a .pptx file is involved…
来源: cowhub
✅ skill-creator
Create, install, or update skills…
来源: builtin
⏸️ image-vision (已禁用)
图片理解和视觉分析
来源: builtin
```
**浏览技能广场**（查看 Hub 上所有可安装的技能）：
<CodeGroup>
```text 对话
/skill list --remote
```
```bash 终端
cow skill list --remote
```
</CodeGroup>
**选项：**
| 选项 | 说明 | 默认值 |
| --- | --- | --- |
| `--remote`, `-r` | 浏览 Skill Hub 远程技能列表 | 否 |
| `--page` | 远程列表分页页码 | 1 |
## search
在技能广场中搜索技能。
<CodeGroup>
```text 对话
/skill search pptx
```
```bash 终端
cow skill search pptx
```
</CodeGroup>
## install
安装技能。通过统一的 `install` 命令，可一键安装来自 **Cow 技能广场、GitHub、ClawHub** 以及任意 URL（zip 压缩包、SKILL.md 链接）上的技能，无需手动下载和配置。
**从 Cow 技能广场安装（推荐）：**
<CodeGroup>
```text 对话
/skill install pptx
```
```bash 终端
cow skill install pptx
```
</CodeGroup>
**从 GitHub 安装：**
<CodeGroup>
```text 对话
# 安装仓库中的所有技能（自动扫描包含 SKILL.md 的子目录）
/skill install larksuite/cli
# 指定子目录，只安装单个技能
/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im
# 使用 # 指定子目录
/skill install larksuite/cli#skills/lark-minutes
```
```bash 终端
# 安装仓库中的所有技能（自动扫描包含 SKILL.md 的子目录）
cow skill install larksuite/cli
# 指定子目录，只安装单个技能
cow skill install https://github.com/larksuite/cli/tree/main/skills/lark-im
# 使用 # 指定子目录
cow skill install larksuite/cli#skills/lark-minutes
```
</CodeGroup>
支持完整的 GitHub URL 和 `owner/repo` 简写。对于 mono-repo（一个仓库中包含多个技能），不指定子目录时会自动发现并批量安装所有技能；指定子目录时只安装该目录下的技能。
**从 ClawHub 安装：**
<CodeGroup>
```text 对话
/skill install clawhub:baidu-search
```
```bash 终端
cow skill install clawhub:baidu-search
```
</CodeGroup>
**从 URL 安装：**
<CodeGroup>
```text 对话
# 从 zip 压缩包安装（支持单个或批量）
/skill install https://cdn.link-ai.tech/skills/pptx.zip
# 从 SKILL.md 链接安装
/skill install https://example.com/path/to/SKILL.md
```
```bash 终端
# 从 zip 压缩包安装（支持单个或批量）
cow skill install https://cdn.link-ai.tech/skills/pptx.zip
# 从 SKILL.md 链接安装
cow skill install https://example.com/path/to/SKILL.md
```
</CodeGroup>
支持从 zip / tar.gz 压缩包 URL 安装，解压后自动扫描包含 `SKILL.md` 的目录，支持单个或批量安装。也支持直接从 `SKILL.md` 文件链接安装，会自动解析技能名称和描述。
安装成功后会显示技能名称、描述和来源，例如：
```
✅ baidu-search
百度搜索：使用百度搜索引擎检索信息…
来源: clawhub
```
## uninstall
卸载已安装的技能。
<CodeGroup>
```text 对话
/skill uninstall pptx
```
```bash 终端
cow skill uninstall pptx
```
</CodeGroup>
<Warning>
卸载操作会删除技能目录下的所有文件，此操作不可恢复。
</Warning>
## enable / disable
启用或禁用技能，禁用后技能不会被 Agent 调用。
<CodeGroup>
```text 对话
/skill enable pptx
/skill disable pptx
```
```bash 终端
cow skill enable pptx
cow skill disable pptx
```
</CodeGroup>
## info
查看已安装技能的详细信息，包括 `SKILL.md` 内容预览。
<CodeGroup>
```text 对话
/skill info pptx
```
```bash 终端
cow skill info pptx
```
</CodeGroup>
## 技能来源
安装的技能会记录来源信息，可通过 `/skill list` 查看：
| 来源标识 | 说明 |
| --- | --- |
| `builtin` | 项目内置技能 |
| `cowhub` | 从 CowAgent Skill Hub 安装 |
| `github` | 从 GitHub URL 直接安装 |
| `clawhub` | 从 ClawHub 安装 |
| `url` | 从 SKILL.md URL 安装 |
| `local` | 本地创建的技能 |

182
docs/zh/guide/manual-install.mdx Normal file
View File

@@ -0,0 +1,182 @@
---
title: 手动安装
description: 手动部署 CowAgent（源码 / Docker）
---
## 源码部署
### 1. 克隆项目代码
```bash
git clone https://github.com/zhayujie/CowAgent
cd CowAgent/
```
<Tip>
若遇到网络问题可使用国内仓库地址：https://gitee.com/zhayujie/CowAgent
</Tip>
### 2. 安装依赖
核心依赖（必选）：
```bash
pip3 install -r requirements.txt
```
扩展依赖（可选，建议安装）：
```bash
pip3 install -r requirements-optional.txt
```
> 国内网络可使用镜像源加速：`pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`
### 3. 安装 Cow CLI
安装命令行工具，用于管理服务和技能：
```bash
pip3 install -e .
```
安装后即可使用 `cow` 命令：
```bash
cow help
```
<Note>
此步骤为推荐操作。安装后可以使用 `cow start`、`cow stop`、`cow update` 等命令管理服务，也可以使用 `cow skill` 管理技能。如果不安装 CLI，可以使用 `./run.sh` 或 `python3 app.py` 运行。
</Note>
### 3.1 安装浏览器工具（可选）
如需使用浏览器工具（控制浏览器访问网页、填写表单等），运行：
```bash
cow install-browser
```
该命令会自动安装 Playwright 和 Chromium 浏览器。详细说明参考 [浏览器工具文档](/zh/tools/browser)。
<Note>
浏览器工具依赖较重（~300MB），如不需要可跳过，不影响其他功能正常使用。
</Note>
### 4. 配置
复制配置文件模板并编辑：
```bash
cp config-template.json config.json
```
在 `config.json` 中填写模型 API Key 和通道类型等配置，详细说明参考各 [模型文档](/zh/models/minimax)。
### 5. 运行
**使用 Cow CLI 运行（推荐）：**
```bash
cow start
```
**或者本地前台运行：**
```bash
python3 app.py
```
运行后默认启动 Web 控制台，访问 `http://localhost:9899` 开始对话和管理Agent。
**服务器后台运行（不使用 CLI 时）：**
```bash
nohup python3 app.py & tail -f nohup.out
```
<Tip>
**服务器公网访问 Web 控制台**：默认 `web_host` 仅监听 `127.0.0.1`（本机访问），需公网访问时请在 `config.json` 中将 `web_host` 设为 `0.0.0.0`，同时强烈建议设置 `web_password` 启用鉴权。此外还需在防火墙/安全组中放行 `9899` 端口，建议仅对指定 IP 开放以保证安全。
</Tip>
## Docker 部署
使用 Docker 部署无需下载源码和安装依赖。Agent模式下更推荐使用源码部署以获得更多系统访问能力。
<Note>
需要安装 [Docker](https://docs.docker.com/engine/install/) 和 docker-compose。
</Note>
**1. 下载配置文件**
```bash
curl -O https://cdn.link-ai.tech/code/cow/docker-compose.yml
```
打开 `docker-compose.yml` 填写所需配置。
**2. 启动容器**
```bash
sudo docker compose up -d
```
**3. 查看日志**
```bash
sudo docker logs -f chatgpt-on-wechat
```
<Tip>
**Docker 公网访问 Web 控制台**：在 `docker-compose.yml` 中将 `WEB_HOST` 设为 `0.0.0.0`（容器内默认绑定 `127.0.0.1` 无法从宿主机外访问），同时强烈建议设置 `WEB_PASSWORD` 启用鉴权。此外需确保 `9899` 端口正确映射到宿主机，并在防火墙/安全组放行该端口。
</Tip>
## 核心配置项
<Tabs>
<Tab title="源码部署（config.json）">
```json
{
"channel_type": "web",
"model": "deepseek-v4-flash",
"deepseek_api_key": "",
"agent": true,
"agent_workspace": "~/cow",
"agent_max_context_tokens": 40000,
"agent_max_context_turns": 30,
"agent_max_steps": 15,
"cow_lang": "auto"
}
```
</Tab>
<Tab title="Docker 部署（docker-compose.yml）">
```yaml
environment:
CHANNEL_TYPE: 'web'
MODEL: 'deepseek-v4-flash'
DEEPSEEK_API_KEY: 'your-api-key'
DEEPSEEK_API_BASE: 'https://api.deepseek.com/v1'
AGENT: 'True'
AGENT_MAX_CONTEXT_TOKENS: 40000
AGENT_MAX_CONTEXT_TURNS: 30
AGENT_MAX_STEPS: 15
COW_LANG: 'auto'
```
</Tab>
</Tabs>
| 参数 | 环境变量 | 说明 | 默认值 |
| --- | --- | --- | --- |
| `channel_type` | `CHANNEL_TYPE` | 接入渠道类型 | `web` |
| `model` | `MODEL` | 模型名称 | `deepseek-v4-flash` |
| `agent` | `AGENT` | 是否启用 Agent 模式 | `true` |
| `agent_workspace` | - | Agent 工作空间路径 | `~/cow` |
| `agent_max_context_tokens` | `AGENT_MAX_CONTEXT_TOKENS` | 最大上下文 tokens | `40000` |
| `agent_max_context_turns` | `AGENT_MAX_CONTEXT_TURNS` | 最大上下文记忆轮次 | `30` |
| `agent_max_steps` | `AGENT_MAX_STEPS` | 单次任务最大决策步数 | `15` |
| `cow_lang` | `COW_LANG` | 界面、命令文案、系统提示词等的语言，`auto` 自动检测，可设为 `zh` / `en` | `auto` |
<Tip>
全部配置项可在项目 [`config.py`](https://github.com/zhayujie/CowAgent/blob/master/config.py) 文件中查看。Docker 部署时，配置项名称需转为大写环境变量格式。
</Tip>

58
docs/zh/guide/quick-start.mdx Normal file
View File

@@ -0,0 +1,58 @@
---
title: 一键安装
description: 使用脚本一键安装和管理 CowAgent
---
项目提供了一键安装、配置、启动、管理程序的脚本，推荐使用脚本快速运行。
支持 Linux、macOS、Windows 操作系统，需安装 Python 3.7 ~ 3.12（推荐 3.9）。
## 安装命令
<Tabs>
<Tab title="Linux / macOS">
```bash
bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
```
</Tab>
<Tab title="Windows (PowerShell)">
```powershell
irm https://cdn.link-ai.tech/code/cow/run.ps1 | iex
```
</Tab>
</Tabs>
脚本自动执行以下流程：
1. 检查 Python 环境（需要 Python 3.7+）
2. 安装必要工具（git、curl 等）
3. 克隆项目代码到 `~/CowAgent`
4. 安装 Python 依赖和 Cow CLI
5. 引导配置 AI 模型和通信渠道
6. 启动服务
运行后默认启动 Web 控制台，访问 `http://localhost:9899` 开始对话和管理Agent。
<Note>
**服务器部署需要公网访问控制台时**，请在 `config.json` 中将 `web_host` 设为 `0.0.0.0`（默认仅监听 `127.0.0.1` 本机访问），同时强烈建议设置 `web_password` 启用鉴权。然后通过 `http://<server-ip>:9899` 访问，并确保防火墙/安全组放行 `9899` 端口。
</Note>
## 管理命令
安装完成后，使用 `cow` CLI 管理服务：
| 命令 | 说明 |
| --- | --- |
| `cow start` | 启动服务 |
| `cow stop` | 停止服务 |
| `cow restart` | 重启服务 |
| `cow status` | 查看运行状态 |
| `cow logs` | 查看实时日志 |
| `cow update` | 更新代码并重启 |
| `cow install-browser` | 安装浏览器工具依赖 |
更多命令和用法参考 [命令文档](/zh/cli/index)。
<Note>
如果 `cow` 命令不可用，也可以使用 `./run.sh <命令>`（Linux/macOS）或 `.\scripts\run.ps1 <命令>`（Windows）作为替代，功能等效。
</Note>

61
docs/zh/guide/upgrade.mdx Normal file
View File

@@ -0,0 +1,61 @@
---
title: 更新升级
description: CowAgent 的升级方式说明
---
## 命令升级（推荐）
使用 `cow update` 一键完成代码更新和服务重启：
```bash
cow update
```
该命令会自动完成以下流程：
1. 拉取最新代码（`git pull`）
2. 停止当前服务
3. 更新 Python 依赖
4. 重新安装 CLI
5. 启动服务
<Note>
如果未安装 Cow CLI，也可以使用 `./run.sh update` 完成相同操作。
</Note>
## 手动升级
在项目根目录下执行：
```bash
git pull
pip3 install -r requirements.txt
pip3 install -e .
```
更新完成后重启服务：
```bash
# 使用 Cow CLI (推荐)
cow restart
# 或使用 run.sh
./run.sh restart
# 或使用 nohup 直接运行
kill $(ps -ef | grep app.py | grep -v grep | awk '{print $2}')
nohup python3 app.py & tail -f nohup.out
```
## Docker 升级
在 `docker-compose.yml` 所在目录下执行：
```bash
sudo docker compose pull
sudo docker compose up -d
```
<Tip>
升级前建议备份 `config.json` 配置文件。Docker 环境下如需保留数据，可通过 volume 挂载持久化工作空间目录。
</Tip>

87
docs/zh/intro/architecture.mdx Normal file
View File

@@ -0,0 +1,87 @@
---
title: 项目架构
description: CowAgent 2.0 的系统架构和核心设计
---
CowAgent 2.0 从简单的聊天机器人全面升级为超级智能助理，采用 Agent 架构设计，具备自主思考、规划任务、长期记忆和技能扩展等能力。
## 系统架构
CowAgent 的整体架构由以下核心模块组成：
<img src="https://cdn.jsdelivr.net/gh/zhayujie/cowagent-assets@main/architecture/zh/architecture.jpg" alt="CowAgent Architecture" />
| 模块 | 说明 |
| --- | --- |
| **Plan** | 理解用户意图，将复杂任务分解为多步骤计划，循环调用工具直到完成目标 |
| **Memory** | 自动将重要信息持久化为核心记忆和日级记忆，支持关键词和向量混合检索，跨会话保持上下文连续性 |
| **Knowledge** | 以主题维度组织结构化知识，Agent 自主整理有价值信息为 Markdown 页面，维护索引和交叉引用，构建持续增长的知识网络 |
| **Tools** | Agent 访问操作系统资源的核心能力，内置文件读写、终端执行、浏览器操作、定时调度、记忆检索、联网搜索等 10+ 种工具 |
| **Skills** | 加载和管理 Skills，支持从 Skill Hub、GitHub 等一键安装，或通过对话创建自定义技能 |
| **Models** | 模型层，统一接入 OpenAI、Claude、Gemini、DeepSeek、MiniMax、GLM、Qwen 等国内外主流大语言模型 |
| **Channels** | 消息通道层，负责接收和发送消息，支持 Web 控制台、微信、飞书、钉钉、企微、公众号等，统一消息协议 |
| **CLI** | 命令行系统，提供终端命令（`cow`）和对话命令（`/`），支持进程管理、技能安装、配置修改、知识库管理等操作 |
## Agent 模式
启用 Agent 模式后，CowAgent 会以自主智能体的方式运行，核心工作流如下：
1. **接收消息** — 通过通道接收用户输入
2. **理解意图** — 分析任务需求和上下文
3. **规划任务** — 将复杂任务分解为多个步骤
4. **调用工具** — 选择合适的工具执行每个步骤
5. **记忆与知识更新** — 将重要信息存入长期记忆，将结构化知识整理至知识库
6. **返回结果** — 将执行结果发送回用户
## 工作空间
Agent 的工作空间默认位于 `~/cow` 目录，用于存储系统提示词、记忆文件、技能文件等：
```
~/cow/
├── SYSTEM.md # Agent system prompt
├── USER.md # User profile
├── MEMORY.md # Core memory
├── memory/ # Long-term memory storage
│ └── YYYY-MM-DD.md # Daily memory
├── knowledge/ # Personal knowledge base
│ ├── index.md # Knowledge index
│ └── <category>/ # Topic-based pages
└── skills/ # Custom skills
├── skill-1/
└── skill-2/
```
秘钥文件单独存储在 `~/.cow` 目录（出于安全考虑）：
```
~/.cow/
└── .env # Secret keys for skills
```
## 核心配置
在 `config.json` 中配置 Agent 模式的核心参数：
```json
{
"agent": true,
"agent_workspace": "~/cow",
"agent_max_context_tokens": 40000,
"agent_max_context_turns": 30,
"agent_max_steps": 15,
"enable_thinking": false,
"cow_lang": "auto"
}
```
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `agent` | 是否启用 Agent 模式 | `true` |
| `agent_workspace` | 工作空间路径 | `~/cow` |
| `agent_max_context_tokens` | 最大上下文 token 数 | `50000` |
| `agent_max_context_turns` | 最大上下文记忆轮次 | `20` |
| `agent_max_steps` | 单次任务最大决策步数 | `20` |
| `enable_thinking` | 是否启用深度思考模式 | `false` |
| `knowledge` | 是否启用个人知识库 | `true` |
| `cow_lang` | 界面、命令文案、系统提示词等的语言，`auto` 自动检测，可设为 `zh` / `en` | `auto` |

142
docs/zh/intro/features.mdx Normal file
View File

@@ -0,0 +1,142 @@
---
title: 功能介绍
description: CowAgent 长期记忆、个人知识库、任务规划、技能系统、CLI 命令、浏览器工具详细说明
---
## 1. 长期记忆
> 记忆系统让 Agent 能够长期记住重要信息，采用三层记忆流转架构：对话上下文（短期）→ 天级记忆（中期）→ MEMORY.md（长期），形成完整的记忆生命周期。
第一次启动 Agent 时，Agent 会主动询问关键信息，并记录至工作空间（默认 `~/cow`）中的智能体设定、用户身份、记忆文件中。
在后续的长期对话中，Agent 会在需要时智能记录或检索记忆，并对自身设定、用户偏好、记忆文件等进行不断更新。每日自动执行 **梦境蒸馏（Deep Dream）**，将分散的天级记忆整合为精炼的长期记忆，同时生成叙事风格的梦境日记。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260203000455.png" width="800" />
</Frame>
详细说明请参考 [长期记忆](/memory) 和 [梦境蒸馏](/zh/memory/deep-dream)。
## 2. 个人知识库
> 知识库系统让 Agent 能够持续积累和组织结构化知识。与按时间线记录的记忆不同，知识库以主题为维度，将文章、对话洞察、学习材料等整理为互相关联的 Markdown 页面，形成持续增长的知识网络。
Agent 会在对话中自动将有价值的信息整理为知识页面，维护交叉引用和索引，通过 Web 控制台可浏览文档和查看知识图谱。知识库存储在工作空间的 `~/cow/knowledge/` 目录下。
- **自动整理**：Agent 在对话中自主提取和整理结构化知识，维护索引和交叉引用
- **知识图谱**：基于页面间的交叉引用自动构建知识图谱，Web 控制台提供可视化关系图浏览
- **对话联动**：Agent 回复中引用的知识文档链接可在 Web 控制台中直接点击跳转查看
- **CLI 管理**：通过 `/knowledge` 命令查看统计、浏览目录，通过 `/knowledge on|off` 开关功能
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260413105435.png" width="800" />
</Frame>
详细说明请参考 [个人知识库](/knowledge)。
## 3. 任务规划和工具调用
工具是 Agent 访问操作系统资源的核心，Agent 会根据任务需求智能选择和调用工具，完成文件读写、命令执行、定时任务等各类操作。内置工具的实现在项目的 `agent/tools/` 目录下。
**主要工具：** 文件读写编辑、Bash 终端、浏览器操作、文件发送、定时调度、记忆搜索、联网搜索、环境配置等。
### 3.1 终端和文件访问
针对操作系统的终端和文件的访问能力，是最基础和核心的工具，其他很多工具或技能都是基于此进行扩展。用户可通过手机端与 Agent 交互，操作个人电脑或服务器上的资源：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202181130.png" width="800" />
</Frame>
### 3.2 编程能力
基于编程能力和系统访问能力，Agent 可以实现从信息搜索、图片等素材生成、编码、测试、部署、Nginx 配置修改、发布的 **Vibecoding 全流程**，通过手机端简单的一句命令完成应用的快速 demo：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260318211018.png" width="800" />
</Frame>
### 3.3 定时任务
基于 `scheduler` 工具实现动态定时任务，支持**一次性任务、固定时间间隔、Cron 表达式**三种形式，任务触发可选择**固定消息发送**或 **Agent 动态任务**执行两种模式：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202195402.png" width="800" />
</Frame>
### 3.4 浏览器操作
内置 `browser` 工具，Agent 可控制浏览器访问网页、填写表单、点击元素、截图，支持动态 JS 渲染页面。运行 `cow install-browser` 一键安装，自动适配服务器（无头模式）和桌面环境：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260401115728.png" width="750" />
</Frame>
### 3.5 环境变量管理
技能所需的秘钥存储在环境变量文件中，由 `env_config` 工具进行管理，你可以通过对话的方式更新秘钥，工具内置安全保护和脱敏策略：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202234939.png" width="800" />
</Frame>
## 4. 技能系统
技能系统为 Agent 提供无限的扩展性，每个 Skill 由说明文件、运行脚本（可选）、资源（可选）组成，描述如何完成特定类型的任务。通过 Skill 可以让 Agent 遵循说明完成复杂流程、调用各类工具或对接第三方系统。
- [Skill Hub](https://skills.cowagent.ai/)：开放的技能广场，汇集官方推荐、社区贡献和第三方技能，支持一键安装。
- **内置技能：** 在项目的 `skills/` 目录下，包含技能创造器、图像识别、LinkAI 智能体、网页抓取等。内置 Skill 根据依赖条件（API Key、系统命令等）自动判断是否启用。
- **自定义技能：** 由用户通过对话创建，存放在工作空间中（`~/cow/skills/`），可实现任何复杂的业务流程和第三方系统对接。
安装技能：`/skill install <名称>` 或 `cow skill install <名称>`，支持从 Skill Hub、GitHub、ClawHub、URL 等来源安装。
### 4.1 创建技能
通过 `skill-creator` 技能可以通过对话的方式快速创建技能。你可以让 Agent 将某个工作流程固化为技能，或者把任意接口文档和示例发送给 Agent，让他直接完成对接：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202202247.png" width="800" />
</Frame>
### 4.2 搜索和图像识别
- **联网搜索：** 内置 `web_search` 工具，支持多种搜索引擎，配置 `BOCHA_API_KEY` 或 `LINKAI_API_KEY` 后启用。
- **图像识别：** 内置 `openai-image-vision` 技能，可使用 `gpt-4.1-mini`、`gpt-4.1` 等模型，依赖 `OPENAI_API_KEY`。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202213219.png" width="800" />
</Frame>
### 4.3 技能广场
访问 [skills.cowagent.ai](https://skills.cowagent.ai/) 浏览所有可用技能，或在对话中执行：
```text
/skill list --remote # 浏览技能广场
/skill search <关键词> # 搜索技能
/skill install <名称> # 一键安装
```
同时还支持安装Github、ClawHub、LinkAI等第三方平台上的所有技能，详情查看 [技能安装](/zh/skills/install)
<img src="https://cdn.link-ai.tech/doc/20260401110103.png" width="750" />
## 5. CLI 命令系统
CowAgent 提供两种命令交互方式，覆盖服务管理、技能安装、配置调整等日常运维操作：
- **终端 CLI：** 在系统终端执行 `cow <命令>`，支持 `start`、`stop`、`restart`、`update`、`status`、`logs`、`skill` 等
- **对话命令：** 在对话中输入 `/<命令>`，Web 控制台输入 `/` 可弹出指令菜单快速选择
```bash
cow start # 启动服务
cow stop # 停止服务
cow update # 更新并重启
cow skill install pptx # 安装技能
cow install-browser # 安装浏览器工具
```
详细命令参考 [命令总览](https://docs.cowagent.ai/cli)。
<img src="https://cdn.link-ai.tech/doc/20260401114549.png" width="750" />

84
docs/zh/intro/index.mdx Normal file
View File

@@ -0,0 +1,84 @@
---
title: 项目介绍
description: CowAgent - 基于大模型的超级AI助理
---
<div align="center">
<img src="https://cdn.link-ai.tech/doc/78c5dd674e2c828642ecc0406669fed7.png" alt="CowAgent" width="450px"/>
</div>
**CowAgent** 是基于大模型的超级AI助理，能够主动思考和任务规划、操作计算机和外部资源、创造和执行Skills、拥有长期记忆和知识库并不断成长。
CowAgent 支持灵活切换多种模型，能处理文本、语音、图片、文件等多模态消息，可接入微信、飞书、钉钉、企业微信应用、微信公众号、网页中使用，7×24小时运行于你的个人电脑或服务器中。
<CardGroup cols={2}>
<Card title="GitHub" icon="github" href="https://github.com/zhayujie/CowAgent">
开源代码仓库，欢迎 Star 和贡献
</Card>
<Card title="免部署在线体验" icon="cloud" href="https://link-ai.tech/cowagent/create">
无需安装，立即在线体验 CowAgent
</Card>
</CardGroup>
## 核心能力
<CardGroup cols={2}>
<Card title="复杂任务规划" icon="brain" href="/zh/intro/architecture">
能够理解复杂任务并自主规划执行，持续思考和调用各类工具和技能直到完成目标。
</Card>
<Card title="长期记忆" icon="database" href="/memory">
三层记忆流转（上下文→天级记忆→全局记忆），每日梦境蒸馏整理，支持关键词及向量检索。
</Card>
<Card title="个人知识库" icon="book" href="/knowledge">
自动整理结构化知识，支持知识图谱可视化，通过交叉引用构建持续增长的知识网络。
</Card>
<Card title="技能系统" icon="puzzle-piece" href="/zh/skills/index">
实现了Skills创建和运行的引擎，内置多种技能，并支持通过自然语言对话完成自定义Skills开发。
</Card>
<Card title="工具系统" icon="wrench" href="/zh/tools/index">
内置文件读写、终端执行、浏览器操作、定时任务、消息发送等工具，Agent 可自主调用工具完成复杂任务。
</Card>
<Card title="命令系统" icon="terminal" href="/zh/cli/index">
提供终端 CLI 和对话中的命令，支持进程管理、技能安装、配置修改、上下文查看等常用操作。
</Card>
<Card title="多模型支持" icon="microchip" href="/zh/models/index">
支持 OpenAI, Claude, Gemini, DeepSeek, MiniMax, GLM, Qwen, Kimi, Doubao 等国内外主流模型厂商。
</Card>
<Card title="多通道接入" icon="server" href="/zh/channels/weixin">
支持运行在本地计算机或服务器，可集成到微信、网页、飞书、钉钉、微信公众号、企业微信应用中使用。
</Card>
</CardGroup>
## 快速体验
在终端执行以下命令，即可一键安装、配置、启动 CowAgent：
<Tabs>
<Tab title="Linux / macOS">
```bash
bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh)
```
</Tab>
<Tab title="Windows (PowerShell)">
```powershell
irm https://cdn.link-ai.tech/code/cow/run.ps1 | iex
```
</Tab>
</Tabs>
运行后默认会启动 Web 控制台，通过访问 `http://localhost:9899` 可以在网页端进行对话、配置、应用通道接入等操作。
<CardGroup cols={2}>
<Card title="快速开始" icon="rocket" href="/zh/guide/quick-start">
查看完整的安装和运行指南
</Card>
<Card title="项目架构" icon="sitemap" href="/zh/intro/architecture">
了解 CowAgent 的系统架构设计
</Card>
</CardGroup>
## 社区
添加小助手微信加入开源项目交流群：
<img width="140" src="https://img-1317903499.cos.ap-guangzhou.myqcloud.com/docs/open-community.png" />

96
docs/zh/knowledge/index.mdx Normal file
View File

@@ -0,0 +1,96 @@
---
title: 个人知识库
description: CowAgent 的个人知识库系统 — 结构化知识沉淀、自动整理与知识图谱
---
个人知识库是 Agent 的长期结构化知识存储，保存在工作空间的 `knowledge/` 目录下。与按时间线组织的记忆不同，知识库以主题为维度，将用户分享的文章、对话中的洞察、学习材料等整理为互相关联的 Markdown 页面，形成可持续增长的知识网络。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260413105435.png" width="800" />
</Frame>
## 核心概念
### 知识 vs 记忆
| 维度 | 知识库（knowledge/） | 长期记忆（memory/） |
| --- | --- | --- |
| 组织方式 | 按主题分类、互相关联 | 按时间线、日期文件 |
| 写入方式 | Agent 主动整理结构化内容 | 上下文裁剪时自动摘要 |
| 内容特点 | 提炼后的结构化知识 | 原始对话摘要 |
| 典型用途 | 学习笔记、技术文档、项目知识 | 对话历史、事件记录 |
### 目录结构
```
~/cow/knowledge/
├── index.md # 知识索引，所有页面的入口
├── log.md # 变更日志，记录每次写入
├── concepts/ # 概念类知识
│ └── machine-learning.md
├── entities/ # 实体类知识（人物、组织、工具）
│ └── openai.md
└── sources/ # 来源类知识（文章、论文）
└── llm-wiki.md
```
目录结构是灵活的 — Agent 会根据实际内容自动创建合适的分类目录。用户也可以通过对话的方式自定义目录组织方式。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260413110104.png" width="800" />
</Frame>
## 自动整理
知识库的写入是 Agent 的自主行为，在以下场景中触发：
- **用户分享文章或文档** — Agent 自动提取关键信息，创建结构化知识页面
- **对话产生有价值的结论** — Agent 将洞察整理为知识页面，并与已有知识建立关联
- **用户主动要求整理** — 用户可以通过对话指导 Agent 组织和更新知识
<Frame>
<img src="https://cdn.link-ai.tech/doc/17aad553d3e9e428c52ff9dc31726fda.png" width="800" />
</Frame>
每个知识页面都包含与其他页面的交叉引用链接，逐步构建起一个知识图谱。
## 知识检索
Agent 在对话中可以通过以下方式检索知识：
- **索引查阅** — 通过 `knowledge/index.md` 快速定位相关知识页面
- **语义搜索** — 通过 `memory_search` 工具对知识库内容进行语义检索
- **直接读取** — 通过 `memory_get` 工具读取特定知识文件
## Web 控制台
Web 控制台提供了专用的「知识」模块，支持：
- **文档浏览** — 树状目录结构，可搜索、可折叠，点击查看文档内容
- **知识图谱** — 可视化展示知识之间的关联关系，节点可直接跳转至文档
- **对话联动** — Agent 回复中引用的知识文档链接可直接点击跳转查看
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260413105402.png" width="800" />
</Frame>
## CLI 命令
通过 `/knowledge` 命令管理知识库：
| 命令 | 说明 |
| --- | --- |
| `/knowledge` | 显示知识库统计信息 |
| `/knowledge list` | 以树状结构显示文件目录 |
| `/knowledge on` | 开启知识库功能 |
| `/knowledge off` | 关闭知识库功能 |
## 相关配置
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `knowledge` | 是否启用个人知识库功能 | `true` |
| `agent_workspace` | 工作空间路径，知识库存储在此目录的 `knowledge/` 子目录下 | `~/cow` |

81
docs/zh/memory/context.mdx Normal file
View File

@@ -0,0 +1,81 @@
---
title: 短期记忆
description: 对话上下文 — 消息管理、压缩策略和上下文操作
---
对话上下文是 Agent 的短期记忆，包含当前会话中的所有消息（用户输入、Agent 回复、工具调用及结果）。合理管理上下文对于 Agent 的推理质量和成本控制至关重要。
## 上下文结构
每一轮对话由以下消息组成：
```
用户消息 → Agent 思考 → 工具调用 → 工具结果 → ... → Agent 最终回复
```
一轮中可能包含多次工具调用（Agent 的决策步数由 `agent_max_steps` 控制），所有工具调用和结果都会保留在上下文中，直到被压缩或裁剪。
## 关键配置
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `agent_max_context_tokens` | 上下文最大 token 预算 | `50000` |
| `agent_max_context_turns` | 上下文最大对话轮次 | `20` |
| `agent_max_steps` | 单轮对话最大决策步数（工具调用次数） | `15` |
可通过 `config.json` 或对话中的 `/config` 命令修改。
## 压缩策略
当上下文超出限制时，系统会自动执行压缩以释放空间。整个过程分为多个阶段：
### 1. 工具结果截断
在每次决策循环开始前，系统会检查历史轮次中的工具调用结果。超过 **20000 字符** 的工具结果会被截断，仅保留首尾内容和截断说明。当前轮次的工具结果不受影响。
### 2. 轮次裁剪
当对话轮次超过 `agent_max_context_turns` 时：
- 裁剪 **最早一半** 的完整轮次（保证工具调用链的完整性）
- 被裁剪的消息会通过 LLM 总结后**写入当天的日级记忆文件**
- LLM 摘要完成后，同时将摘要**注入到保留消息的第一条用户消息开头**，帮助模型在后续对话中保持上下文连贯性
- 摘要注入在后台异步完成，不阻塞当前回复；注入的摘要在下一轮对话时生效
### 3. Token 预算裁剪
裁剪轮次后，如果 token 数仍超出预算：
- **轮次 < 5 时**：对所有轮次进行**文本压缩** — 每轮只保留第一条用户文本和最后一条 Agent 回复，去掉中间的工具调用链
- **轮次 ≥ 5 时**：再次裁剪**前半轮次**，被丢弃内容同样写入记忆并注入上下文摘要
### 4. 溢出应急处理
当模型 API 返回上下文溢出错误时：
1. 先将当前所有消息总结写入记忆
2. 执行激进裁剪（工具结果限制 10K 字符、用户文本限制 10K、最多保留 5 轮）
3. 如果仍然溢出，清空整个对话上下文
## 会话持久化
对话消息会持久化到本地数据库，服务重启后自动恢复。恢复策略：
- 恢复最近的 **`max(3, max_context_turns / 6)`** 轮对话
- 只保留每轮的**用户文本和 Agent 最终回复**，不恢复中间工具调用链
- 超过 **30 天**的历史会话自动清理
## 操作命令
在对话中可以使用以下命令管理上下文：
| 命令 | 说明 |
| --- | --- |
| `/context` | 查看当前上下文统计（消息数、角色分布、总字符数） |
| `/context clear` | 清空当前会话上下文 |
| `/config agent_max_context_tokens 80000` | 调整上下文 token 预算 |
| `/config agent_max_context_turns 30` | 调整上下文轮次上限 |
<Tip>
清空上下文后，Agent 会"忘记"之前的对话内容。被裁剪和清空的内容如果已经写入长期记忆，仍可通过记忆检索找回。
</Tip>

94
docs/zh/memory/deep-dream.mdx Normal file
View File

@@ -0,0 +1,94 @@
---
title: 梦境蒸馏
description: Deep Dream — 从对话到永久记忆的自动蒸馏机制
---
梦境蒸馏（Deep Dream）是 CowAgent 记忆系统的核心整理机制，负责将分散的天级记忆蒸馏为精炼的长期记忆，并生成梦境日记。
## 记忆流转
CowAgent 的记忆从短期到长期经历三个阶段：
```
对话上下文（短期）→ 天级记忆（中期）→ MEMORY.md（长期）
```
### 1. 对话 → 天级记忆
当对话上下文被裁剪或每日定时总结时，系统使用 LLM 将对话内容摘要为关键事件，写入当天的天级记忆文件 `memory/YYYY-MM-DD.md`。
触发时机：
- **上下文裁剪** — 轮次或 token 超限时，裁剪的内容被总结写入
- **每日定时** — 23:55 自动触发全量总结
- **API 溢出** — 紧急保存当前对话摘要
### 2. 天级记忆 → MEMORY.md（蒸馏）
每日总结完成后，Deep Dream 自动执行蒸馏：
1. **读取材料** — 当前 `MEMORY.md` + 当天的天级记忆
2. **LLM 蒸馏** — 去重、合并、修剪、提取新信息
3. **覆写 MEMORY.md** — 输出精炼后的长期记忆
4. **生成梦境日记** — 记录整理过程的发现和洞察
### 3. MEMORY.md 的作用
`MEMORY.md` 会被注入到每次对话的系统提示词中，让 Agent 始终了解用户的偏好、决策和关键事实。因此它必须保持精炼——Deep Dream 会控制在约 30 条以内。
## 蒸馏规则
Deep Dream 遵循以下整理规则：
| 操作 | 说明 |
| --- | --- |
| **合并提炼** | 含义相近的多条合并为一条高密度表述 |
| **新增萃取** | 从天级记忆中提取偏好、决策、人物、经验等 |
| **冲突更新** | 新信息与旧条目矛盾时，以新信息为准 |
| **清理无效** | 删除临时性记录、空白条目、格式残留 |
| **删除冗余** | 已被更精炼表述涵盖的旧条目删除 |
## 梦境日记
每次蒸馏会生成一篇梦境日记，保存在 `memory/dreams/YYYY-MM-DD.md`，用叙事风格记录：
- 发现了哪些重复或矛盾
- 从天级记忆中提取了什么新洞察
- 做了哪些清理和优化
- 整体感受和观察
梦境日记可在 Web 控制台的「记忆管理 → 梦境日记」tab 中查看。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260414110032.png" width="800" />
</Frame>
## 手动触发
除了每日自动执行外，也可以在对话中手动触发：
```text
/memory dream [N]
```
- `N`：整理近 N 天的记忆（默认 3 天，最大 30 天）
- 蒸馏在后台异步执行，完成后在对话中通知结果
- Web 端通知包含可点击链接，直接跳转查看 MEMORY.md 和梦境日记
- 无需 Agent 初始化，首次对话前即可使用
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260414120158.png" width="800" />
</Frame>
<Tip>
首次部署后可以手动执行一次 `/memory dream 30`，将历史天级记忆全量蒸馏到 MEMORY.md。
</Tip>
## 安全机制
| 机制 | 说明 |
| --- | --- |
| **无新内容跳过** | 没有天级记忆时不执行蒸馏，避免空覆写 |
| **输入去重** | 定时任务中，输入材料未变化时自动跳过 |
| **异步执行** | 蒸馏在后台线程运行，不阻塞对话 |
| **顺序保证** | 定时任务中，天级 flush 全部完成后才启动蒸馏 |
| **禁止编造** | 提示词明确约束只能基于已有材料整理，不得推测或添加 |

71
docs/zh/memory/index.mdx Normal file
View File

@@ -0,0 +1,71 @@
---
title: 长期记忆
description: CowAgent 的长期记忆系统 — 文件持久化、自动写入与混合检索
---
长期记忆保存在工作空间文件中，跨会话持久存在。Agent 在对话中通过检索工具按需加载历史记忆，也会在上下文裁剪时自动将对话摘要写入长期记忆。
<img src="https://cdn.link-ai.tech/doc/memory-architecture-zh.jpeg" alt="Memory Architecture" />
## 记忆类型
### 核心记忆（MEMORY.md）
存储在 `~/cow/MEMORY.md` 中，包含用户的长期偏好、重要决策、关键事实等不会随时间淡化的信息。Agent 可通过工具读写此文件来维护长期知识。
### 日级记忆（memory/YYYY-MM-DD.md）
存储在 `~/cow/memory/` 目录下，按日期命名（如 `2026-03-08.md`），记录每天的对话摘要和关键事件。仅在首次写入时创建，避免生成空文件。
### 梦境日记（memory/dreams/YYYY-MM-DD.md）
Deep Dream（记忆蒸馏）过程的副产物，记录每次整理的发现、去重合并操作和新洞察。存储在 `~/cow/memory/dreams/` 目录下，按日期命名。
## 自动写入
Agent 通过以下机制自动将对话内容持久化为长期记忆：
- **上下文裁剪时** — 当对话轮次或 token 超出配置上限时，裁剪最早一半的上下文，使用 LLM 将被裁剪的内容总结为关键信息写入当天记忆文件，并将摘要异步注入到保留的上下文中，帮助模型保持对话连贯性
- **每日定时总结** — 每天 23:55 自动触发一次全量总结，防止低活跃日无记忆留存（内容无变化时自动跳过）
- [梦境蒸馏（Deep Dream）](/zh/memory/deep-dream) — 每日总结完成后自动执行，将天级记忆蒸馏合并到 MEMORY.md，并生成梦境日记
- **API 上下文溢出时** — 当模型 API 返回上下文溢出错误时，紧急保存当前对话摘要
所有记忆写入均在后台异步执行（LLM 总结 + 文件写入），不阻塞正常对话回复。
## 记忆检索
记忆系统支持混合检索模式：
- **关键词检索** — 基于 FTS5 全文索引匹配历史记忆，支持 BM25 排序
- **向量检索** — 基于 embedding 语义相似度搜索，即使表述不同也能找到相关记忆
Agent 会在对话中根据需要自动触发记忆检索，将相关历史信息纳入上下文。检索结果按混合评分排序（默认向量权重 0.7、关键词权重 0.3），日级记忆会随时间衰减（半衰期 30 天），核心记忆不衰减。
## 相关文件
工作空间（默认 `~/cow`）中与记忆相关的文件：
| 文件 | 说明 |
| --- | --- |
| `AGENT.md` | Agent 的人格和行为设定 |
| `USER.md` | 用户身份信息和偏好 |
| `RULE.md` | 自定义规则和约束 |
| `MEMORY.md` | 核心记忆（长期） |
| `memory/YYYY-MM-DD.md` | 日级记忆（按需创建） |
| `memory/dreams/YYYY-MM-DD.md` | 梦境日记（Deep Dream 自动生成） |
## Web 控制台
在 Web 控制台的记忆管理页面中，可浏览记忆文件和梦境日记，支持通过 Tab 切换查看：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260414171014.png" width="800" />
</Frame>
## 相关配置
| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `agent_workspace` | 工作空间路径，记忆文件存储在此目录下 | `~/cow` |
| `agent_max_context_tokens` | 最大上下文 token 数，超出时裁剪并总结写入记忆 | `50000` |
| `agent_max_context_turns` | 最大上下文轮次，超出时裁剪并总结写入记忆 | `20` |

50
docs/zh/models/claude.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: Claude
description: Anthropic Claude 模型配置（文本对话 + 图像理解）
---
Claude 由 Anthropic 提供，支持文本对话与图像理解，主流 Sonnet / Opus 模型均原生支持视觉，无需额外指定 Vision 模型。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "claude-opus-4-8",
"claude_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 支持 `claude-opus-4-8`、`claude-opus-4-7`、`claude-sonnet-4-6`、`claude-opus-4-6`、`claude-sonnet-4-5`、`claude-sonnet-4-0`、`claude-3-5-sonnet-latest` 等，参考 [官方模型](https://docs.anthropic.com/en/docs/about-claude/models/overview) |
| `claude_api_key` | 在 [Claude 控制台](https://console.anthropic.com/settings/keys) 创建 |
| `claude_api_base` | 可选，默认为 `https://api.anthropic.com/v1`，可改为第三方代理 |
### 模型选择
| 模型 | 适用场景 |
| --- | --- |
| `claude-opus-4-8` | 默认推荐，最新旗舰，复杂推理与长链路任务效果最佳 |
| `claude-opus-4-7` | 上一代 Opus 旗舰 |
| `claude-sonnet-4-6` | 性价比与速度平衡，成本更低 |
| `claude-opus-4-6` / `claude-sonnet-4-5` / `claude-sonnet-4-0` | 更早的旗舰，价格更低 |
## 图像理解
配置 `claude_api_key` 后 Agent 的 Vision 工具会自动使用 Claude 主模型识别图像，无需额外配置。
如需手动指定 Vision 模型，可在配置文件中显式配置：
```json
{
"tools": {
"vision": {
"model": "claude-sonnet-4-6"
}
}
}
```

140
docs/zh/models/coding-plan.mdx Normal file
View File

@@ -0,0 +1,140 @@
---
title: Coding Plan
description: Coding Plan 模式模型配置
---
> Coding Plan 是各厂商推出的编程包月套餐，适合高频使用 Agent 的场景。CowAgent 支持通过 OpenAI 兼容方式接入各厂商的 Coding Plan 接口。
<Note>
Coding Plan 的 API Base 和 API Key 通常与普通按量计费接口不通用，请在各厂商平台单独获取。
</Note>
## 通用配置格式
所有厂商均可使用 OpenAI 兼容协议接入，可在web控制台快速配置。设置模型厂商为**OpenAI**，选择自定义模型并填入模型编码，最后填写对应厂商的API Base 和 API Key：
<img src="https://cdn.link-ai.tech/doc/20260318113134.png" width="800"/>
也可通过 `config.json` 配置文件直接修改：
```json
{
"bot_type": "openai",
"model": "模型名称",
"open_ai_api_base": "厂商 Coding Plan API Base",
"open_ai_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `bot_type` | 固定为 `openai`（OpenAI 兼容方式） |
| `model` | 各厂商支持的模型名称 |
| `open_ai_api_base` | 各厂商 Coding Plan 专用 API Base |
| `open_ai_api_key` | 各厂商 Coding Plan 专用 API Key |
---
## 阿里云
```json
{
"bot_type": "openai",
"model": "qwen3.5-plus",
"open_ai_api_base": "https://coding.dashscope.aliyuncs.com/v1",
"open_ai_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | `qwen3.5-plus`、`qwen3-max-2026-01-23`、`qwen3-coder-next`、`qwen3-coder-plus`、`glm-5`、`glm-4.7`、`kimi-k2.5`、`MiniMax-M2.5` |
| `open_ai_api_base` | `https://coding.dashscope.aliyuncs.com/v1` |
| `open_ai_api_key` | Coding Plan 专用 Key（与按量计费接口不通用） |
官方文档：[快速开始](https://help.aliyun.com/zh/model-studio/coding-plan-quickstart?spm=a2c4g.11186623.help-menu-2400256.d_0_2_1.70115203zi5Igc)、[模型列表](https://help.aliyun.com/zh/model-studio/coding-plan)
---
## MiniMax
```json
{
"bot_type": "openai",
"model": "MiniMax-M2.5",
"open_ai_api_base": "https://api.minimaxi.com/v1",
"open_ai_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | `MiniMax-M2.5`、`MiniMax-M2.5-highspeed`、`MiniMax-M2.1`、`MiniMax-M2` |
| `open_ai_api_base` | 国内：`https://api.minimaxi.com/v1`；海外：`https://api.minimax.io/v1` |
| `open_ai_api_key` | Coding Plan 专用 Key（与按量计费接口不通用） |
官方文档：[国内 Key 获取](https://platform.minimaxi.com/docs/coding-plan/quickstart)、[模型列表](https://platform.minimaxi.com/docs/guides/pricing-coding-plan)、[国际 Key 获取](https://platform.minimax.io/docs/coding-plan/quickstart)
---
## 智谱 GLM
```json
{
"bot_type": "openai",
"model": "glm-4.7",
"open_ai_api_base": "https://open.bigmodel.cn/api/coding/paas/v4",
"open_ai_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | `glm-5`、`glm-4.7`、`glm-4.6`、`glm-4.5`、`glm-4.5-air` |
| `open_ai_api_base` | 中国区：`https://open.bigmodel.cn/api/coding/paas/v4`；全球区：`https://api.z.ai/api/coding/paas/v4` |
| `open_ai_api_key` | API Key 与普通接口通用 |
官方文档：[国内版快速开始](https://docs.bigmodel.cn/cn/coding-plan/quick-start)、[国际版快速开始](https://docs.z.ai/devpack/quick-start)
---
## 火山引擎
```json
{
"bot_type": "openai",
"model": "Doubao-Seed-2.0-Code",
"open_ai_api_base": "https://ark.cn-beijing.volces.com/api/coding/v3",
"open_ai_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | `Doubao-Seed-2.0-Code`、`Doubao-Seed-2.0-pro`、`Doubao-Seed-2.0-lite`、`Doubao-Seed-Code`、`MiniMax-M2.5`、`Kimi-K2.5`、`GLM-4.7`、`DeepSeek-V3.2` |
| `open_ai_api_base` | `https://ark.cn-beijing.volces.com/api/coding/v3` |
| `open_ai_api_key` | API Key 与普通接口通用 |
官方文档：[快速开始](https://www.volcengine.com/docs/82379/1928261?lang=zh)
---
## Kimi
```json
{
"bot_type": "moonshot",
"model": "kimi-for-coding",
"moonshot_base_url": "https://api.kimi.com/coding/v1",
"moonshot_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 填写 `kimi-for-coding` 会自动更新模型，或指定模型例如 `kimi-k2.6` |
| `moonshot_base_url` | `https://api.kimi.com/coding/v1` |
| `moonshot_api_key` | Coding Plan 专用 Key（与按量计费接口不通用） |
官方文档：[Key 获取](https://www.kimi.com/code/docs/)

62
docs/zh/models/custom.mdx Normal file
View File

@@ -0,0 +1,62 @@
---
title: 自定义
description: 自定义厂商配置，适用于第三方 API 代理和本地模型
---
适用于通过 OpenAI 兼容协议接入的第三方模型服务或本地部署的模型，例如：
- **第三方 API 代理**：使用统一的 API Base 调用多种模型
- **本地模型**：通过 Ollama、vLLM、LocalAI 等工具在本地部署的模型
- **私有化部署**：企业内部部署的模型服务
<Note>
与 `openai` 厂商的区别：选择自定义厂商后，通过 `/config model` 切换模型时，不会自动切换厂商类型，始终使用自定义的 API 地址。
</Note>
## 文本对话
### 第三方 API 代理
```json
{
"bot_type": "custom",
"model": "",
"custom_api_key": "YOUR_API_KEY",
"custom_api_base": "https://{your-proxy.com}/v1"
}
```
| 参数 | 说明 |
| --- | --- |
| `bot_type` | 必须设为 `custom` |
| `model` | 模型名称，填写代理服务支持的任意模型名 |
| `custom_api_key` | API 密钥，由代理服务提供 |
| `custom_api_base` | API 地址，由代理服务提供，需兼容 OpenAI 协议 |
### 本地模型
本地模型通常不需要 API Key，只需填写 API Base：
```json
{
"bot_type": "custom",
"model": "qwen3.5:27b",
"custom_api_base": "http://localhost:11434/v1"
}
```
常见的本地部署工具及默认地址：
| 工具 | 默认 API Base |
| --- | --- |
| [Ollama](https://ollama.com) | `http://localhost:11434/v1` |
| [vLLM](https://docs.vllm.ai) | `http://localhost:8000/v1` |
| [LocalAI](https://localai.io) | `http://localhost:8080/v1` |
### 切换模型
自定义厂商下切换模型时，只会修改 `model`，不会改变 `bot_type` 和 API 地址：
```
/config model qwen3.5:27b
```

72
docs/zh/models/deepseek.mdx Normal file
View File

@@ -0,0 +1,72 @@
---
title: DeepSeek
description: DeepSeek 模型配置（文本对话 + 思考模式）
---
DeepSeek 是当前 Agent 模式默认推荐的厂商之一，主打高性价比的文本对话和任务规划能力。
## 文本对话
```json
{
"model": "deepseek-v4-flash",
"deepseek_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 支持 `deepseek-v4-flash`（默认）、`deepseek-v4-pro` |
| `deepseek_api_key` | 在 [DeepSeek 平台](https://platform.deepseek.com/api_keys) 创建 |
| `deepseek_api_base` | 可选，默认为 `https://api.deepseek.com/v1`，可修改为第三方代理地址 |
### 模型选择
| 模型 | 适用场景 |
| --- | --- |
| `deepseek-v4-flash` | 默认推荐，速度快、成本低 |
| `deepseek-v4-pro` | 更智能，复杂任务效果更强 |
## 思考模式
V4 系列（`deepseek-v4-flash` / `deepseek-v4-pro`）支持显式的「思考模式」：模型在输出最终回答前，先输出一段思维链（`reasoning_content`），从而提升答案质量。
### 开关
通过全局配置 `enable_thinking` 控制，也可在 web控制台 - 配置页面中进行切换：
```json
{
"enable_thinking": true
}
```
- `true`：所有渠道下模型都会先思考再作答。Web 控制台会展示思考过程，IM 渠道（微信 / 企微 / 钉钉 / 飞书）虽不展示但同样获得更好答案。
- `false`：关闭思考，响应更快，首字延迟更低。
### 推理强度
思考模式下可通过 `reasoning_effort` 控制推理强度：
```json
{
"enable_thinking": true,
"reasoning_effort": "high"
}
```
| 取值 | 适用场景 |
| --- | --- |
| `high`（默认） | 日常 Agent 任务，思考与速度的平衡 |
| `max` | 复杂编码、长链路规划、严格约束的任务，推理更深但耗时与输出 token 更多 |
`reasoning_effort` 仅在 `enable_thinking` 为 `true` 时生效；模型不支持思考模式时该字段自动忽略。
### 行为说明
- **采样参数**：思考模式下 `temperature`、`top_p`、`presence_penalty`、`frequency_penalty` 会被服务端忽略（不会报错），CowAgent 会自动跳过传入。
- **多轮工具调用**：当历史中包含工具调用时，DeepSeek 要求所有 assistant 消息必须回传 `reasoning_content`。CowAgent 会自动处理回传逻辑，跨轮次切换思考开关也不会出错。
<Tip>
默认使用 `deepseek-v4-flash`；复杂任务可使用 `deepseek-v4-pro`；需要深度推理可开启 `enable_thinking`。
</Tip>

66
docs/zh/models/doubao.mdx Normal file
View File

@@ -0,0 +1,66 @@
---
title: 豆包 Doubao
description: 豆包（火山方舟）模型配置（文本 / 图像理解 / 图像生成 / 向量）
---
豆包（火山方舟）支持文本对话、图像理解、图像生成（Seedream）和向量能力，一份 `ark_api_key` 即可启用全部能力。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "doubao-seed-2-0-pro-260215",
"ark_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 可填 `doubao-seed-2-0-pro-260215`、`doubao-seed-2-0-code-preview-260215`、`doubao-seed-2-0-lite-260215` 等 |
| `ark_api_key` | 在 [火山方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/apikey) 创建 |
| `ark_base_url` | 可选，默认为 `https://ark.cn-beijing.volces.com/api/v3` |
## 图像理解
配置 `ark_api_key` 后 Agent 的 Vision 工具会自动使用 `doubao-seed-2-0-pro-260215` 识别图像，无需额外配置。
如需手动指定 Vision 模型：
```json
{
"tools": {
"vision": {
"model": "doubao-seed-2-0-pro-260215"
}
}
}
```
## 图像生成
```json
{
"skills": {
"image-generation": {
"model": "seedream-5.0-lite"
}
}
}
```
可选模型：`seedream-5.0-lite`、`seedream-4.5`。
## 向量
```json
{
"embedding_provider": "doubao",
"embedding_model": "doubao-embedding-vision-251215"
}
```
默认模型 `doubao-embedding-vision-251215`（多模态 embedding），可在配置文件中通过 `embedding_dimensions` 指定 1024 或 2048 维。修改 embedding 后需执行 `/memory rebuild-index` 命令重建索引。

59
docs/zh/models/gemini.mdx Normal file
View File

@@ -0,0 +1,59 @@
---
title: Gemini
description: Google Gemini 模型配置（文本对话 + 图像理解 + 图像生成）
---
Google Gemini 支持文本对话、图像理解和图像生成（Nano Banana 系列），一个 `gemini_api_key` 即可启用全部能力。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "gemini-3.5-flash",
"gemini_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 推荐 `gemini-3.5-flash`，亦支持 `gemini-3.1-pro-preview`、`gemini-3.1-flash-lite-preview`、`gemini-3-flash-preview`、`gemini-3-pro-preview` 等，参考 [官方文档](https://ai.google.dev/gemini-api/docs/models) |
| `gemini_api_key` | 在 [Google AI Studio](https://aistudio.google.com/app/apikey) 创建 |
| `gemini_api_base` | 可选，默认为 `https://generativelanguage.googleapis.com`，可改为第三方代理 |
## 图像理解
Gemini 全系列模型均原生支持视觉，配置 `gemini_api_key` 后 Agent 的 Vision 工具会自动使用主模型识别图像，无需额外配置。
如需手动指定 Vision 模型：
```json
{
"tools": {
"vision": {
"model": "gemini-3.1-flash-lite-preview"
}
}
}
```
## 图像生成
```json
{
"skills": {
"image-generation": {
"model": "gemini-3.1-flash-image-preview"
}
}
}
```
| 模型 ID | 别名 |
| --- | --- |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 |
| `gemini-3-pro-image-preview` | Nano Banana Pro |
| `gemini-2.5-flash-image` | Nano Banana |

56
docs/zh/models/glm.mdx Normal file
View File

@@ -0,0 +1,56 @@
---
title: 智谱 GLM
description: 智谱 AI GLM 模型配置（文本 / 图像理解 / 语音识别 / 向量）
---
智谱 AI 支持文本对话、图像理解、语音识别（ASR）和向量（Embedding），一份 `zhipu_ai_api_key` 即可启用全部能力。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "glm-5.1",
"zhipu_ai_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 可填 `glm-5.1`、`glm-5-turbo`、`glm-5`、`glm-4.7`、`glm-4-plus`、`glm-4-flash`、`glm-4-air` 等，参考 [模型编码](https://bigmodel.cn/dev/api/normal-model/glm-4) |
| `zhipu_ai_api_key` | 在 [智谱 AI 控制台](https://www.bigmodel.cn/usercenter/proj-mgmt/apikeys) 创建 |
| `zhipu_ai_api_base` | 可选，默认为 `https://open.bigmodel.cn/api/paas/v4` |
## 图像理解
智谱 chat 系列模型（`glm-5.1`、`glm-5-turbo` 等）不支持视觉，视觉调用统一路由到 `glm-5v-turbo`。配置 `zhipu_ai_api_key` 后 Agent 的 Vision 工具会自动使用该模型，无需在配置文件中显式指定。
## 语音识别
```json
{
"voice_to_text": "zhipu",
"voice_to_text_model": "glm-asr-2512"
}
```
| 参数 | 说明 |
| --- | --- |
| `voice_to_text` | 设为 `zhipu` 启用智谱 ASR |
| `voice_to_text_model` | 可选，默认 `glm-asr-2512` |
凭证自动复用 `zhipu_ai_api_key`。语音文件建议小于 25MB，超大文件可能被服务端拒绝。
## 向量
```json
{
"embedding_provider": "zhipu",
"embedding_model": "embedding-3"
}
```
可选模型：`embedding-3`、`embedding-2`。修改 embedding 后需执行 `/memory rebuild-index` 命令重建索引。

40
docs/zh/models/index.mdx Normal file
View File

@@ -0,0 +1,40 @@
---
title: 模型概览
description: CowAgent 支持的模型厂商及能力矩阵
---
CowAgent 支持国内外主流厂商的大语言模型，模型接口实现在项目的 `models/` 目录下。除文本对话外，部分厂商还提供视觉理解、图像生成、语音识别、语音合成、向量等能力，可在 Agent 流程中按需调用。
## 模型能力总览
各厂商提供的能力一览。「文本」指主对话模型，其余列表示该厂商可承担对应 Agent 能力。
| 厂商 | 代表模型 | 文本 | 图像理解 | 图像生成 | 语音识别 | 语音合成 | 向量 |
| --- | --- | :-: | :-: | :-: | :-: | :-: | :-: |
| [DeepSeek](/zh/models/deepseek) | deepseek-v4-flash / pro | ✅ | | | | | |
| [MiniMax](/zh/models/minimax) | MiniMax-M2.7 | ✅ | ✅ | ✅ | | ✅ | |
| [Claude](/zh/models/claude) | claude-opus-4-8 | ✅ | ✅ | | | | |
| [Gemini](/zh/models/gemini) | gemini-3.5-flash | ✅ | ✅ | ✅ | | | |
| [OpenAI](/zh/models/openai) | gpt-5.5、o 系列 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [智谱 GLM](/zh/models/glm) | glm-5.1、glm-5v-turbo | ✅ | ✅ | | ✅ | | ✅ |
| [通义千问](/zh/models/qwen) | qwen3.7-max | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [豆包 Doubao](/zh/models/doubao) | doubao-seed-2.0 系列 | ✅ | ✅ | ✅ | | | ✅ |
| [Kimi](/zh/models/kimi) | kimi-k2.6 | ✅ | ✅ | | | | |
| [百度千帆](/zh/models/qianfan) | ernie-5.1 | ✅ | ✅ | | | | |
| [小米 MiMo](/zh/models/mimo) | mimo-v2.5-pro / v2.5 | ✅ | ✅ | | | ✅ | |
| [LinkAI](/zh/models/linkai) | 多厂商 100+ 模型统一接入 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [自定义](/zh/models/custom) |本地模型 / 三方代理 | ✅ | | | | | |
<Tip>
Web 控制台中各项能力（视觉 / 图像 / 语音识别 / 语音合成 / 向量 / 网络搜索）均可独立配置厂商与模型，互相之间不强制绑定。
</Tip>
## 配置方式
**方式一（推荐）：** 通过 [Web 控制台](/zh/channels/web) 在线管理模型与各项能力，无需手动编辑配置文件：
<img width="900" src="https://cdn.link-ai.tech/doc/20260521212527.png" />
**方式二：** 手动编辑 `config.json`，根据所选模型填写对应的模型名称和 API Key。每个模型也支持 OpenAI 兼容方式接入，将 `bot_type` 设为 `openai`，配置 `open_ai_api_base` 和 `open_ai_api_key` 即可。

41
docs/zh/models/kimi.mdx Normal file
View File

@@ -0,0 +1,41 @@
---
title: Kimi
description: Kimi（Moonshot）模型配置（文本对话 + 图像理解）
---
Kimi 由 Moonshot 提供，支持文本对话与图像理解，`kimi-k2.x` 系列原生支持视觉。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "kimi-k2.6",
"moonshot_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 可填 `kimi-k2.6`、`kimi-k2.5`、`kimi-k2`、`moonshot-v1-8k`、`moonshot-v1-32k`、`moonshot-v1-128k` |
| `moonshot_api_key` | 在 [Moonshot 控制台](https://platform.moonshot.cn/console/api-keys) 创建 |
| `moonshot_base_url` | 可选，默认为 `https://api.moonshot.cn/v1` |
## 图像理解
配置 `moonshot_api_key` 后 Agent 的 Vision 工具会自动使用 `kimi-k2.6` 识别图像，无需额外配置。
如需手动指定 Vision 模型：
```json
{
"tools": {
"vision": {
"model": "kimi-k2.6"
}
}
}
```

103
docs/zh/models/linkai.mdx Normal file
View File

@@ -0,0 +1,103 @@
---
title: LinkAI
description: 通过 LinkAI 平台统一接入文本、视觉、图像、语音与向量能力
---
通过一份 `linkai_api_key` 即可访问 OpenAI、Claude、Gemini、DeepSeek、MiniMax、Qwen、Kimi、豆包 等主流厂商的全部能力。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"use_linkai": true,
"linkai_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `use_linkai` | 设为 `true` 启用 |
| `linkai_api_key` | 在 [控制台](https://link-ai.tech/console/interface) 创建 |
| `model` | 可填写 [模型列表](https://link-ai.tech/console/models) 中任意编码 |
前往 [模型服务](https://link-ai.tech/console/models) 了解更多。
## 图像理解
配置完成后 Agent 的 Vision 工具会自动调用网关上的多模态模型，无需额外配置。如需手动指定 Vision 模型：
```json
{
"tools": {
"vision": {
"model": "gpt-5.4-mini"
}
}
}
```
可选模型：`gpt-4.1-mini`、`gpt-5.4-mini`、`qwen3.6-plus`、`doubao-seed-2-0-pro-260215`、`kimi-k2.6`、`claude-sonnet-4-6`、`gemini-3.1-flash-lite-preview` 等。
## 图像生成
```json
{
"skills": {
"image-generation": {
"model": "gpt-image-2"
}
}
}
```
| 模型 ID | 别名 |
| --- | --- |
| `gpt-image-2` | OpenAI |
| `gemini-3.1-flash-image-preview` | Nano Banana 2 |
| `gemini-3-pro-image-preview` | Nano Banana Pro |
| `seedream-5.0-lite` | 字节豆包 Seedream |
## 语音识别
```json
{
"voice_to_text": "linkai"
}
```
ASR 固定使用 Whisper，凭证自动复用 `linkai_api_key`。
## 语音合成
语音合成网关下支持多个底层 TTS 引擎，按 `text_to_voice_model` 选择引擎，音色随引擎切换。
```json
{
"text_to_voice": "linkai",
"text_to_voice_model": "doubao",
"tts_voice_id": "BV001_streaming"
}
```
| `text_to_voice_model` | 引擎说明 |
| --- | --- |
| `tts-1` | OpenAI · 多语种通用（音色 `alloy` / `nova` / `echo` 等） |
| `doubao` | 字节豆包 · 中文音色丰富 |
| `baidu` | 百度 · 中文主播音色 |
不同引擎对应的音色不同，建议在 Web 控制台「模型管理 → 语音合成」中可视化选择。
## 向量
```json
{
"embedding_provider": "linkai",
"embedding_model": "text-embedding-3-small"
}
```
默认模型 `text-embedding-3-small`（OpenAI 兼容）。修改 embedding 后需执行 `/memory rebuild-index` 命令重建索引。

135
docs/zh/models/mimo.mdx Normal file
View File

@@ -0,0 +1,135 @@
---
title: 小米 MiMo
description: 小米 MiMo 模型配置（文本对话 + 图像理解 + 语音合成）
---
小米 MiMo 是原生全模态大模型，单 `mimo_api_key` 即可同时启用文本对话、图像理解与语音合成。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "mimo-v2.5-pro",
"mimo_api_key": "YOUR_API_KEY",
"mimo_api_base": "https://api.xiaomimimo.com/v1"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 默认推荐 `mimo-v2.5-pro`，也可使用 `mimo-v2.5` |
| `mimo_api_key` | 在 [MiMo 开放平台](https://platform.xiaomimimo.com/console/api-keys) 创建 |
| `mimo_api_base` | 可选，默认为 `https://api.xiaomimimo.com/v1` |
### 模型选择
| 模型 | 适用场景 |
| --- | --- |
| `mimo-v2.5-pro` | 旗舰，原生全模态 + Agent 能力，最高 100 万 tokens 上下文 |
| `mimo-v2.5` | 综合版，原生全模态（文本 / 图像 / 视频 / 音频） |
## 思考模式
MiMo V2.5 系列默认开启「思考模式」：模型在输出最终回答前会先输出 `reasoning_content`（思维链），提升复杂任务表现。
通过全局配置 `enable_thinking` 控制是否展示（也可在 Web 控制台 - 配置页面切换）：
```json
{
"enable_thinking": true
}
```
## 图像理解
配置 `mimo_api_key` 后，Agent 的 Vision 工具可以自动使用 MiMo 视觉模型：
- 当主模型本身是多模态时（`mimo-v2.5-pro` / `mimo-v2.5`），直接由主模型识别图像，无需额外配置
- 当主模型是其他厂商时，Vision 工具会根据顺序自动 fallback 到 `mimo-v2.5-pro`
如需手动指定 Vision 模型，可在配置文件中显式配置：
```json
{
"tools": {
"vision": {
"provider": "mimo",
"model": "mimo-v2.5-pro"
}
}
}
```
## 语音合成
```json
{
"text_to_voice": "mimo",
"text_to_voice_model": "mimo-v2.5-tts",
"tts_voice_id": "冰糖"
}
```
| 参数 | 说明 |
| --- | --- |
| `text_to_voice_model` | 当前仅支持 `mimo-v2.5-tts`（预置音色 + 唱歌模式） |
| `tts_voice_id` | 预置音色名（中文音色直接使用中文名作为 ID） |
### 预置音色
| 音色 ID | 说明 |
| --- | --- |
| `冰糖` | 中文 · 女声（默认） |
| `茉莉` | 中文 · 女声 |
| `苏打` | 中文 · 男声 |
| `白桦` | 中文 · 男声 |
| `Mia` | 英文 · 女声 |
| `Chloe` | 英文 · 女声 |
| `Milo` | 英文 · 男声 |
| `Dean` | 英文 · 男声 |
也可在 Web 控制台的「模型管理 → 语音合成」下拉框中可视化选择。
### 风格控制
MiMo TTS 支持在合成文本中嵌入 **音频标签** 来控制情绪、语调、方言、角色甚至唱歌。标签需出现在 **最终被合成为语音的文本（即 Agent 回复内容）** 中，整体风格标签写在开头：
```
(风格)待合成内容
```
支持半角 `()`、全角 `（）` 或 `[]` 三种括号。常见风格示例：
| 类型 | 示例标签 |
| --- | --- |
| 基础情绪 | `开心` `悲伤` `愤怒` `恐惧` `惊讶` `兴奋` `委屈` `平静` `冷漠` |
| 复合情绪 | `怅然` `欣慰` `无奈` `愧疚` `释然` `忐忑` `动情` |
| 整体语调 | `温柔` `高冷` `活泼` `严肃` `慵懒` `俏皮` `深沉` `干练` `凌厉` |
| 音色定位 | `磁性` `醇厚` `清亮` `空灵` `稚嫩` `苍老` `甜美` `沙哑` |
| 人设腔调 | `夹子音` `御姐音` `正太音` `大叔音` `台湾腔` |
| 方言 | `东北话` `四川话` `河南话` `粤语` |
| 角色扮演 | `孙悟空` `林黛玉` |
| 唱歌 | `唱歌`（等价于 `sing` / `singing`） |
示例：
- (磁性)夜已经深了，城市还在呼吸。
- (东北话)哎呀妈呀，这天儿也忒冷了吧！
- (粤语)呢个真係好正啊！
- (唱歌)原谅我这一生不羁放纵爱自由…
也可以在文本任意位置插入细粒度音频标签来控制呼吸、笑声、停顿等，例如：
```
（紧张，深呼吸）呼……冷静，冷静。（语速加快）自我介绍我背了五十遍了，应该没问题。
```
完整标签列表参见 [MiMo 语音合成文档](https://platform.xiaomimimo.com/docs/zh-CN/usage-guide/speech-synthesis-v2.5)。
<Tip>
CowAgent 在调用 TTS 时会将 Agent 的回复原文（含 `(...)` 标签）直接送入 MiMo 合成。你可以在人设 / 系统提示词里要求模型「在回复开头用 `(风格)` 标签控制语气」，即可让 IM 渠道（微信 / 飞书 / 钉钉 / 企微）的语音回复带上情绪、方言、唱歌等效果。
</Tip>

71
docs/zh/models/minimax.mdx Normal file
View File

@@ -0,0 +1,71 @@
---
title: MiniMax
description: MiniMax 模型配置（文本 / 图像理解 / 图像生成 / 语音合成）
---
MiniMax 支持文本对话、图像理解、图像生成与语音合成，一份 `minimax_api_key` 即可启用全部能力。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "MiniMax-M2.7",
"minimax_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 可填 `MiniMax-M2.7`、`MiniMax-M2.7-highspeed`、`MiniMax-M2.5`、`MiniMax-M2.1`、`MiniMax-M2.1-lightning`、`MiniMax-M2` 等 |
| `minimax_api_key` | 在 [MiniMax 控制台](https://platform.minimaxi.com/user-center/basic-information/interface-key) 创建 |
## 图像理解
MiniMax 的 M2.x 系列 chat 模型本身不支持视觉，视觉调用统一路由到 `MiniMax-Text-01`。配置 `minimax_api_key` 后 Agent 的 Vision 工具会自动使用该模型，无需在配置文件中显式指定。
## 图像生成
```json
{
"skills": {
"image-generation": {
"model": "image-01"
}
}
}
```
可选模型：`image-01`。
## 语音合成
```json
{
"text_to_voice": "minimax",
"text_to_voice_model": "speech-2.8-hd",
"tts_voice_id": "female-shaonv"
}
```
| 参数 | 说明 |
| --- | --- |
| `text_to_voice_model` | `speech-2.8-hd`（情绪渲染、自然听感）、`speech-2.8-turbo`（极速）、`speech-2.6-hd`、`speech-2.6-turbo` |
| `tts_voice_id` | 音色 ID，支持中文 / 粤语 / 英 / 日 / 韩，共 70+ 种 |
常用音色示例：
| 音色 ID | 说明 |
| --- | --- |
| `female-shaonv` | 中文 · 少女（女） |
| `female-yujie` | 中文 · 御姐（女） |
| `female-tianmei` | 中文 · 甜美女性（女） |
| `male-qn-jingying` | 中文 · 精英青年（男） |
| `male-qn-badao` | 中文 · 霸道青年（男） |
| `Cantonese_GentleLady` | 粤语 · 温柔女声 |
| `English_Graceful_Lady` | 英文 · Graceful Lady |
完整音色（中文 / 粤语 / 英 / 日 / 韩共 70+ 种）可参考 [系统音色列表](https://platform.minimaxi.com/docs/faq/system-voice-id)，也可在 Web 控制台的「模型管理 → 语音合成」下拉框中可视化选择。

103
docs/zh/models/openai.mdx Normal file
View File

@@ -0,0 +1,103 @@
---
title: OpenAI
description: OpenAI 模型配置（文本 / 视觉 / 图像 / 语音 / 向量）
---
OpenAI 是覆盖最完整的厂商，可同时承担文本对话、视觉理解、图像生成、语音识别（ASR）、语音合成（TTS）和向量（Embedding）能力。一份 `open_ai_api_key` 即可让 Agent 用到全部能力。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "gpt-5.5",
"open_ai_api_key": "YOUR_API_KEY",
"open_ai_api_base": "https://api.openai.com/v1"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 与 OpenAI 接口的 [model 参数](https://platform.openai.com/docs/models) 一致，支持 `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.4-nano`、`gpt-5` 系列、`gpt-4.1`、o 系列等；Agent 模式默认 `gpt-5.5`，追求性价比可改为 `gpt-5.4` |
| `open_ai_api_key` | 在 [OpenAI 平台](https://platform.openai.com/api-keys) 创建 |
| `open_ai_api_base` | 可选，修改可接入第三方代理 |
| `bot_type` | 使用 OpenAI 官方模型时无需填写；通过兼容协议接入厂商模型时需设为 `openai` |
## 图像理解
`gpt-5.5`、`gpt-5.4`、`gpt-4o`、`gpt-4.1` 等 OpenAI 模型均原生支持视觉，配置 `open_ai_api_key` 后 Agent 的 Vision 工具会自动使用主模型识别图像。若主模型不支持视觉或希望显式指定，可在配置文件中配置：
```json
{
"tools": {
"vision": {
"model": "gpt-5.4-mini"
}
}
}
```
支持的 Vision 模型：`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.4-nano`、`gpt-5`、`gpt-4.1`、`gpt-4.1-mini`、`gpt-4o`。
## 图像生成
在配置文件中指定图像生成模型，Agent 调用图像生成技能时会自动路由到 OpenAI：
```json
{
"skills": {
"image-generation": {
"model": "gpt-image-2"
}
}
}
```
支持的图像生成模型：`gpt-image-2`、`gpt-image-1`。
## 语音识别
```json
{
"voice_to_text": "openai",
"voice_to_text_model": "gpt-4o-mini-transcribe"
}
```
| 参数 | 说明 |
| --- | --- |
| `voice_to_text` | 设为 `openai` 启用 OpenAI 语音识别 |
| `voice_to_text_model` | 可选，默认 `gpt-4o-mini-transcribe`；也可填 `gpt-4o-transcribe`、`whisper-1` |
凭证自动复用 `open_ai_api_key`。
## 语音合成
```json
{
"text_to_voice": "openai",
"text_to_voice_model": "tts-1",
"tts_voice_id": "alloy"
}
```
| 参数 | 说明 |
| --- | --- |
| `text_to_voice_model` | `tts-1`、`tts-1-hd`、`gpt-4o-mini-tts` |
| `tts_voice_id` | 音色：`alloy`、`echo`、`fable`、`onyx`、`nova`、`shimmer`、`ash`、`ballad`、`coral`、`sage`、`verse` |
## 向量
```json
{
"embedding_provider": "openai",
"embedding_model": "text-embedding-3-small"
}
```
可选模型：`text-embedding-3-small`、`text-embedding-3-large`、`text-embedding-ada-002`。修改 embedding 后需执行 `/memory rebuild-index` 命令重建索引。

59
docs/zh/models/qianfan.mdx Normal file
View File

@@ -0,0 +1,59 @@
---
title: 百度千帆
description: 百度千帆 ERNIE 模型配置（文本对话 + 图像理解）
---
百度千帆提供 ERNIE 系列模型，支持文本对话与图像理解。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "ernie-5.1",
"qianfan_api_key": "YOUR_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` |
| `qianfan_api_key` | 千帆 API Key，格式通常以 `bce-v3/` 开头 |
| `qianfan_api_base` | 可选，默认为 `https://qianfan.baidubce.com/v2` |
### 模型选择
| 模型 | 适用场景 |
| --- | --- |
| `ernie-5.1` | 默认推荐，文心新一代旗舰模型，综合能力最强 |
| `ernie-5.0` | 上一代旗舰模型，综合能力优异 |
| `ernie-x1.1` | 深度思考推理模型，幻觉更低、指令遵循与工具调用更强 |
| `ernie-4.5-turbo-128k` | 长上下文和通用对话 |
| `ernie-4.5-turbo-32k` | 通用对话，成本和上下文更均衡 |
## 图像理解
配置 `qianfan_api_key` 后，Agent 的 Vision 工具可以自动使用千帆视觉模型：
- 当主模型本身是多模态时（如 `ernie-5.1`、`ernie-5.0`、`ernie-x1.1`、`ernie-4.5-turbo-vl`），直接由主模型识别图像，无需额外配置
- 当主模型是纯文本时（如 `ernie-4.5-turbo-128k`），Vision 工具会自动 fallback 到 `ernie-4.5-turbo-vl`
如需手动指定 Vision 模型，可在配置文件中显式配置：
```json
{
"tools": {
"vision": {
"model": "ernie-4.5-turbo-vl"
}
}
}
```
<Tip>
新配置推荐使用 `qianfan_api_key`。旧的 `wenxin`、`wenxin-4`、`baidu_wenxin_api_key`、`baidu_wenxin_secret_key` 配置仍保持兼容。
</Tip>

112
docs/zh/models/qwen.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: 通义千问 Qwen
description: 通义千问模型配置（文本 / 图像理解 / 图像生成 / 语音识别 / 语音合成 / 向量）
---
通义千问（DashScope / 百炼）是国内覆盖最完整的厂商之一，文本、图像理解、图像生成、语音识别、语音合成与向量能力均可用一份 `dashscope_api_key` 启用。
<Tip>
通过 Web 控制台的「模型管理」页面可一站式配置以下全部能力，无需手动改配置文件。
</Tip>
## 文本对话
```json
{
"model": "qwen3.6-plus",
"dashscope_api_key": "YOUR_API_KEY"
}
```
| 参数 | 说明 |
| --- | --- |
| `model` | 可填 `qwen3.6-plus`、`qwen3.7-max`、`qwen3.5-plus`、`qwen3-max`、`qwen-max`、`qwen-plus`、`qwen-turbo`、`qwq-plus` 等 |
| `dashscope_api_key` | 在 [百炼控制台](https://bailian.console.aliyun.com/?tab=model#/api-key) 创建，参考 [官方文档](https://bailian.console.aliyun.com/?tab=api#/api) |
## 图像理解
配置 `dashscope_api_key` 后 Agent 的 Vision 工具会自动调用千问的视觉模型识别图像。`qwen3-max` / `qwen3.5-plus` / `qwen3.6-plus` 等模型本身就是多模态；若主模型是纯文本（如 `qwen-turbo`），会自动回落到 `qwen-vl-max`。
如需手动指定 Vision 模型：
```json
{
"tools": {
"vision": {
"model": "qwen3.6-plus"
}
}
}
```
支持模型：`qwen3.6-plus`、`qwen3.5-plus`、`qwen3-max`。
## 图像生成
```json
{
"skills": {
"image-generation": {
"model": "qwen-image-2.0"
}
}
}
```
可选模型：`qwen-image-2.0`、`qwen-image-2.0-pro`。
## 语音识别
```json
{
"voice_to_text": "dashscope",
"voice_to_text_model": "qwen3-asr-flash"
}
```
| 参数 | 说明 |
| --- | --- |
| `voice_to_text` | 设为 `dashscope` 启用通义千问 ASR |
| `voice_to_text_model` | 可选，默认 `qwen3-asr-flash` |
凭证自动复用 `dashscope_api_key`。单段音频建议小于 10MB、时长不超过 300 秒。
## 语音合成
```json
{
"text_to_voice": "dashscope",
"text_to_voice_model": "qwen3-tts-flash",
"tts_voice_id": "Cherry"
}
```
| 参数 | 说明 |
| --- | --- |
| `text_to_voice_model` | 可选，默认 `qwen3-tts-flash`，覆盖普通话、方言与主流外语 |
| `tts_voice_id` | 音色 ID，详见下方常用列表 |
常用音色示例：
| 音色 ID | 说明 |
| --- | --- |
| `Cherry` | 芊悦 · 阳光女声 |
| `Serena` | 苏瑶 · 温柔女声 |
| `Ethan` | 晨煦 · 阳光男声 |
| `Chelsie` | 千雪 · 二次元少女 |
| `Dylan` | 北京话 · 晓东 |
| `Rocky` | 粤语 · 阿强 |
| `Sunny` | 四川话 · 晴儿 |
完整音色（普通话 / 各地方言 / 双语等）可在 Web 控制台的「模型管理 → 语音合成」下拉框中可视化选择。
## 向量
```json
{
"embedding_provider": "dashscope",
"embedding_model": "text-embedding-v4"
}
```
默认模型 `text-embedding-v4`。修改 embedding 后需执行 `/memory rebuild-index` 命令重建索引。

32
docs/zh/releases/overview.mdx Normal file
View File

@@ -0,0 +1,32 @@
---
title: 更新日志
description: CowAgent 版本更新历史
---
| 版本 | 日期 | 说明 |
| --- | --- | --- |
| [2.0.9](/zh/releases/v2.0.9) | 2026.05.22 | 新增模型管理、MCP 协议支持、浏览器登录态持久化、新模型接入（gpt-5.5、gemini-3.5-flash、qwen3.7-max 等）、部署安全加固 |
| [2.0.8](/zh/releases/v2.0.8) | 2026.05.06 | 飞书渠道全面升级（语音、流式输出和Markdown、扫码一键接入）、DeepSeek V4和百度模型新增、定时任务工具增强 |
| [2.0.7](/zh/releases/v2.0.7) | 2026.04.22 | 图像生成技能（六厂商自动路由）、新模型支持（Kimi K2.6、Claude Opus 4.7、GLM 5.1）、知识库增强、Web 控制台优化 |
| [2.0.6](/zh/releases/v2.0.6) | 2026.04.14 | 项目更名、知识库系统、梦境记忆蒸馏、上下文智能压缩、Web 控制台多会话及多项优化 |
| [2.0.5](/zh/releases/v2.0.5) | 2026.04.01 | Cow CLI、Skill Hub 开源、浏览器工具、企微扫码创建、多项优化和修复 |
| [2.0.4](/zh/releases/v2.0.4) | 2026.03.22 | 新增个人微信通道、新模型支持、日文文档、脚本重构及多项修复 |
| [2.0.3](/zh/releases/v2.0.3) | 2026.03.18 | 新增企微智能机器人和 QQ 通道、支持Coding Plan、新增多个模型、Web端文件处理、记忆系统升级 |
| [2.0.2](/zh/releases/v2.0.2) | 2026.02.27 | Web 控制台升级、多通道同时运行、会话持久化 |
| [2.0.1](/zh/releases/v2.0.1) | 2026.02.13 | 内置 Web Search 工具、智能上下文管理、多项修复 |
| [2.0.0](/zh/releases/v2.0.0) | 2026.02.03 | 全面升级为超级 Agent 助理 |
| 1.7.6 | 2025.05.23 | Web Channel 优化、AgentMesh 多智能体插件 |
| 1.7.5 | 2025.04.11 | DeepSeek 模型 |
| 1.7.4 | 2024.12.13 | Gemini 2.0 模型、Web Channel |
| 1.7.3 | 2024.10.31 | 稳定性提升、数据库功能 |
| 1.7.2 | 2024.09.26 | 一键安装脚本、o1 模型 |
| 1.7.0 | 2024.08.02 | 讯飞 4.0 模型、知识库引用 |
| 1.6.9 | 2024.07.19 | gpt-4o-mini、阿里语音识别 |
| 1.6.8 | 2024.07.05 | Claude 3.5、Gemini 1.5 Pro |
| 1.6.0 | 2024.04.26 | Kimi 接入、gpt-4-turbo 升级 |
| 1.5.8 | 2024.03.26 | GLM-4、Claude-3、edge-tts |
| 1.5.2 | 2023.11.10 | 飞书通道、图像识别对话 |
| 1.5.0 | 2023.11.10 | gpt-4-turbo、dall-e-3、tts 多模态 |
| 1.0.0 | 2022.12.12 | 项目创建，首次接入 ChatGPT 模型 |
更多历史版本请查看 [GitHub Releases](https://github.com/zhayujie/CowAgent/releases)。

105
docs/zh/releases/v2.0.0.mdx Normal file
View File

@@ -0,0 +1,105 @@
---
title: v2.0.0
description: CowAgent 2.0 - 从聊天机器人到超级智能助理的全面升级
---
CowAgent 2.0 实现了从聊天机器人到**超级智能助理**的全面升级！现在它能够主动思考和规划任务、拥有长期记忆、操作计算机和外部资源、创造和执行技能，真正理解你并和你一起成长。
**发布日期**：2026.02.03 | [GitHub Release](https://github.com/zhayujie/CowAgent/releases/tag/2.0.0)
## 重点更新
### Agent 核心能力
- **复杂任务规划**：能够理解复杂任务并自主规划执行，持续思考和调用工具直到完成目标，支持多轮推理和上下文理解
- **长期记忆**：自动将对话记忆持久化至本地文件和数据库中，包括全局记忆和天级记忆，支持关键词及向量检索
- **内置系统工具**：内置实现 10+ 种工具，包括文件操作、Bash 终端、浏览器、文件发送、定时任务、记忆管理等
- **Skills**：新增 Skill 运行引擎，内置多种技能，并支持通过自然语言对话完成自定义 Skills 开发
- **安全和成本**：通过秘钥管理工具、提示词控制、系统权限等手段控制 Agent 的访问安全；通过最大记忆轮次、最大上下文 token、工具执行步数对 token 成本进行限制
### 其他更新
- **渠道优化**：飞书及钉钉接入渠道支持长连接接入（无需公网 IP）、支持图片/文件消息的接收和发送
- **模型更新**：新增 claude-sonnet-4-5、gemini-3-pro-preview、glm-4.7、MiniMax-M2.1、qwen3-max 等最新模型
- **部署优化**：增加一键安装、配置、运行、管理的脚本，简化部署流程
## 长期记忆系统
Agent 会在用户分享重要信息时主动存储，也会在对话达到一定长度时自动提取摘要。支持语义搜索和向量检索的混合检索模式。
**首次启动**时，Agent 会主动询问关键信息，并记录至工作空间（默认 `~/cow`）中的智能体设定、用户身份、记忆文件中。
**长期对话**中，Agent 会智能记录或检索记忆，不断更新自身设定、用户偏好，总结经验和教训，真正实现自主思考和持续成长。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260203000455.png" width="800" />
</Frame>
## 任务规划与工具调用
Agent 根据任务需求智能选择和调用工具，完成各类复杂操作。
### 终端和文件访问
最基础和核心的工具能力，用户可通过手机端与 Agent 交互，操作个人电脑或服务器上的资源：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202181130.png" width="800" />
</Frame>
### 应用编程能力
基于编程能力和系统访问能力，Agent 可实现从信息搜索、素材生成、编码、测试、部署、Nginx 配置、发布的 **Vibecoding 全流程**，通过手机端一句命令完成应用快速 demo。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260203121008.png" width="800" />
</Frame>
### 定时任务
支持 **一次性任务、固定时间间隔、Cron 表达式** 三种形式，任务触发可选择 **固定消息发送** 或 **Agent 动态任务执行** 两种模式：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202195402.png" width="800" />
</Frame>
### 环境变量管理
通过 `env_config` 工具管理技能所需秘钥，支持对话式更新，内置安全保护和脱敏策略：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202234939.png" width="800" />
</Frame>
## 技能系统
每个 Skill 由说明文件、运行脚本（可选）、资源（可选）组成，为 Agent 提供无限扩展性。
### 技能创造器
通过对话方式快速创建技能，将工作流程固化或对接任意第三方接口：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202202247.png" width="800" />
</Frame>
### 网页搜索和图像识别
- **网页搜索**：内置 `web_search` 工具，支持多种搜索引擎，配置对应 API Key 即可使用
- **图像识别**：支持 `gpt-4.1-mini`、`gpt-4.1` 等模型，配置 `OPENAI_API_KEY` 即可使用
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202213219.png" width="800" />
</Frame>
### 三方知识库和插件
`linkai-agent` 技能可将 [LinkAI](https://link-ai.tech/) 上的所有智能体作为 Skill 使用，实现多智能体决策：
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202234350.png" width="750" />
</Frame>
## 参与共建
2.0 版本后，项目将持续升级 Agent 能力、拓展接入渠道、内置工具、技能系统，降低模型成本和提升安全性。欢迎 [提出反馈](https://github.com/zhayujie/CowAgent/issues) 和 [贡献代码](https://github.com/zhayujie/CowAgent/pulls)。

36
docs/zh/releases/v2.0.1.mdx Normal file
View File

@@ -0,0 +1,36 @@
---
title: v2.0.1
description: CowAgent 2.0.1 - 内置 Web Search、智能上下文管理、多项修复
---
**发布日期**：2026.02 | [GitHub Release](https://github.com/zhayujie/CowAgent/releases/tag/2.0.1) | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.0..2.0.1)
## 新特性
- **内置 Web Search 工具**：将网络搜索作为 Agent 内置工具集成，降低决策成本 ([4f0ea5d](https://github.com/zhayujie/CowAgent/commit/4f0ea5d7568d61db91ff69c91c429e785fd1b1c2))
- **Claude Opus 4.6 模型支持**：新增对 Claude Opus 4.6 模型的支持 ([#2661](https://github.com/zhayujie/CowAgent/pull/2661))
- **企业微信图片消息识别**：支持企业微信渠道的图片消息识别功能 ([#2667](https://github.com/zhayujie/CowAgent/pull/2667))
## 优化
- **智能上下文管理**：解决聊天上下文溢出问题，新增智能上下文裁剪策略，防止 token 超限 ([cea7fb7](https://github.com/zhayujie/CowAgent/commit/cea7fb7490c53454602bf05955a0e9f059bcf0fd), [8acf2db](https://github.com/zhayujie/CowAgent/commit/8acf2dbdfe713b84ad74b761b7f86674b1c1904d)) [#2663](https://github.com/zhayujie/CowAgent/issues/2663)
- **运行时信息动态更新**：通过动态函数方案实现系统提示词中时间戳等运行时信息的自动更新 ([#2655](https://github.com/zhayujie/CowAgent/pull/2655), [#2657](https://github.com/zhayujie/CowAgent/pull/2657))
- **Skill 提示词优化**：改进 Skill 系统提示词生成逻辑，简化工具描述，提升 Agent 表现 ([6c21833](https://github.com/zhayujie/CowAgent/commit/6c218331b1f1208ea8be6bf226936d3b556ade3e))
- **智谱 AI 自定义 API Base URL**：支持智谱 AI 配置自定义 API Base URL ([#2660](https://github.com/zhayujie/CowAgent/pull/2660))
- **启动脚本优化**：改进 `run.sh` 脚本的交互体验和配置流程 ([#2656](https://github.com/zhayujie/CowAgent/pull/2656))
- **决策轮次日志**：新增 Agent 决策轮次的日志记录，便于调试 ([cb303e6](https://github.com/zhayujie/CowAgent/commit/cb303e6109c50c8dfef1f5e6c1ec47223bf3cd11))
## 问题修复
- **定时任务记忆丢失**：修复 Scheduler 调度器导致的记忆丢失问题 ([a77a874](https://github.com/zhayujie/CowAgent/commit/a77a8741b500a408c6f5c8868856fb4b018fe9db))
- **空工具调用与超长结果**：修复空 tool calls 及过长工具返回结果的异常处理 ([0542700](https://github.com/zhayujie/CowAgent/commit/0542700f9091ebb08c1a56103b0f0f45f24aa621))
- **OpenAI Function Call**：修复 OpenAI 模型的 function call 调用兼容性问题 ([158c87a](https://github.com/zhayujie/CowAgent/commit/158c87ab8b05bae054cc1b4eacdbb64fc1062ba9))
- **Claude 工具名字段**：移除 Claude 模型响应中多余的 tool name 字段 ([eec10cb](https://github.com/zhayujie/CowAgent/commit/eec10cb5db6a3d5bc12ef606606532237d2c5f6e))
- **MiniMax 推理优化**：优化 MiniMax 模型 reasoning content 处理，隐藏思考过程输出 ([c72cda3](https://github.com/zhayujie/CowAgent/commit/c72cda33864bd1542012ee6e0a8bd8c6c88cb5ed), [72b1cac](https://github.com/zhayujie/CowAgent/commit/72b1cacea1ba0d1f3dedacbab2e088e98fd7e172))
- **智谱 AI 思考过程**：隐藏智谱 AI 模型的思考过程展示 ([72b1cac](https://github.com/zhayujie/CowAgent/commit/72b1cacea1ba0d1f3dedacbab2e088e98fd7e172))
- **飞书连接与证书**：修复飞书渠道的 SSL 证书错误和连接异常问题 ([229b14b](https://github.com/zhayujie/CowAgent/commit/229b14b6fcabe7123d53cab1dea39f38dab26d6d), [8674421](https://github.com/zhayujie/CowAgent/commit/867442155e7f095b4f38b0856f8c1d8312b5fcf7))
- **model_type 类型校验**：修复非字符串 `model_type` 导致的 `AttributeError` ([#2666](https://github.com/zhayujie/CowAgent/pull/2666))
## 平台兼容
- **Windows 兼容性适配**：修复 Windows 平台下路径处理、文件编码及 `os.getuid()` 不可用等问题，涉及多个工具模块 ([051ffd7](https://github.com/zhayujie/CowAgent/commit/051ffd78a372f71a967fd3259e37fe19131f83cf), [5264f7c](https://github.com/zhayujie/CowAgent/commit/5264f7ce18360ee4db5dcb4ebe67307977d40014))

98
docs/zh/releases/v2.0.2.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: v2.0.2
description: CowAgent 2.0.2 - Web 控制台升级、多通道同时运行、会话持久化
---
## ✨ 重点更新
### 🖥️ Web 控制台升级
本次对 Web 控制台进行了全面升级，支持流式对话输出、工具执行过程和思考过程的可视化展示，并支持对模型、技能、记忆、通道、Agent 配置的在线查看和管理。
#### 对话界面
支持流式输出，可实时展示 Agent 的思考过程（Reasoning）和工具调用过程（Tool Calls），更直观地观察 Agent 的决策过程：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227180120.png" />
#### 模型管理
支持在线管理模型配置，无需手动编辑配置文件：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173811.png" />
#### 技能管理
支持在线查看和管理 Agent 技能（Skills）：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173403.png" />
#### 记忆管理
支持在线查看和管理 Agent 记忆：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173349.png" />
#### 通道管理
支持在线管理接入通道，支持实时连接/断开操作：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173331.png" />
#### 定时任务
支持在线查看和管理定时任务，包括一次性任务、固定间隔、Cron 表达式等多种调度方式的可视化管理：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173704.png" />
#### 日志
支持在线实时查看 Agent 运行日志，便于监控运行状态和排查问题：
<img width="850" src="https://cdn.link-ai.tech/doc/20260227173514.png" />
相关提交：[f1a1413](https://github.com/zhayujie/CowAgent/commit/f1a1413), [c0702c8](https://github.com/zhayujie/CowAgent/commit/c0702c8), [394853c](https://github.com/zhayujie/CowAgent/commit/394853c), [1c71c4e](https://github.com/zhayujie/CowAgent/commit/1c71c4e), [5e3eccb](https://github.com/zhayujie/CowAgent/commit/5e3eccb), [e1dc037](https://github.com/zhayujie/CowAgent/commit/e1dc037), [5edbf4c](https://github.com/zhayujie/CowAgent/commit/5edbf4c), [7d258b5](https://github.com/zhayujie/CowAgent/commit/7d258b5)
### 🔀 多通道同时运行
支持多个接入通道（如飞书、钉钉、企微应用、Web 等）同时运行，每个通道在独立子线程中启动，互不干扰。
配置方式：在 `config.json` 中通过 `channel_type` 配置多个通道，以逗号分隔，也可在 Web 控制台的通道管理页面中实时连接或断开各通道。
```json
{
"channel_type": "web,feishu,dingtalk"
}
```
相关提交：[4694594](https://github.com/zhayujie/CowAgent/commit/4694594), [7cce224](https://github.com/zhayujie/CowAgent/commit/7cce224), [7d258b5](https://github.com/zhayujie/CowAgent/commit/7d258b5), [c9adddb](https://github.com/zhayujie/CowAgent/commit/c9adddb)
### 💾 会话持久化
会话历史支持持久化存储至本地 SQLite 数据库，服务重启后会话上下文自动恢复，不再丢失。Web 控制台中的历史对话记录也会同步恢复展示。
相关提交：[29bfbec](https://github.com/zhayujie/CowAgent/commit/29bfbec), [9917552](https://github.com/zhayujie/CowAgent/commit/9917552), [925d728](https://github.com/zhayujie/CowAgent/commit/925d728)
### 🤖 新增模型
- **Gemini 3.1 Pro Preview**：新增 `gemini-3.1-pro-preview` 模型支持 ([52d7cad](https://github.com/zhayujie/CowAgent/commit/52d7cad))
- **Claude 4.6 Sonnet**：新增 `claude-4.6-sonnet` 模型支持 ([52d7cad](https://github.com/zhayujie/CowAgent/commit/52d7cad))
- **Qwen3.5 Plus**：新增 `qwen3.5-plus` 模型支持 ([e59a289](https://github.com/zhayujie/CowAgent/commit/e59a289))
- **MiniMax M2.5**：新增 `Minimax-M2.5` 模型支持 ([48db538](https://github.com/zhayujie/CowAgent/commit/48db538))
- **GLM-5**：新增 `glm-5` 模型支持 ([48db538](https://github.com/zhayujie/CowAgent/commit/48db538))
- **Kimi K2.5**：新增 `kimi-k2.5` 模型支持 ([48db538](https://github.com/zhayujie/CowAgent/commit/48db538))
- **Doubao 2.0 Code**：新增 `doubao-2.0-code` 编程专用模型 ([ab28ee5](https://github.com/zhayujie/CowAgent/commit/ab28ee5))
- **DashScope 模型**：新增阿里云 DashScope 模型名称支持 ([ce58f23](https://github.com/zhayujie/CowAgent/commit/ce58f23))
### 🌐 新增官网和文档中心
- **官网上线**：[cowagent.ai](https://cowagent.ai/)
- **文档中心上线**：[docs.cowagent.ai](https://docs.cowagent.ai/)
### 🐛 问题修复
- **Gemini 钉钉图片识别**：修复 Gemini 在钉钉通道中无法处理图片标记的问题 ([05a3304](https://github.com/zhayujie/CowAgent/commit/05a3304)) ([#2670](https://github.com/zhayujie/CowAgent/pull/2670)) Thanks [@SgtPepper114](https://github.com/SgtPepper114)
- **启动脚本依赖**：修复 `run.sh` 脚本的依赖安装问题 ([b6fc9fa](https://github.com/zhayujie/CowAgent/commit/b6fc9fa))
- **裸异常捕获**：将代码中的 `bare except` 替换为 `except Exception`，提升异常处理规范性 ([adca89b](https://github.com/zhayujie/CowAgent/commit/adca89b)) ([#2674](https://github.com/zhayujie/CowAgent/pull/2674)) Thanks [@haosenwang1018](https://github.com/haosenwang1018)
**发布日期**：2026.02.27 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.1...master)

91
docs/zh/releases/v2.0.3.mdx Normal file
View File

@@ -0,0 +1,91 @@
---
title: v2.0.3
description: CowAgent 2.0.3 - 新增企微智能机器人和 QQ 通道、Web 控制台文件处理、记忆系统升级
---
## 🔌 新增接入通道
### 企业微信智能机器人
新增企业微信智能机器人（`wecom_bot`）通道，支持流式卡片消息输出，支持文本和图片消息的接收与回复，可在 Web 控制台中进行通道配置和管理。
接入文档：[企微智能机器人接入](https://docs.cowagent.ai/channels/wecom-bot)。
相关提交：[d4480b6](https://github.com/zhayujie/CowAgent/commit/d4480b6), [a42f31f](https://github.com/zhayujie/CowAgent/commit/a42f31f), [4ecd4df](https://github.com/zhayujie/CowAgent/commit/4ecd4df), [8b45d6c](https://github.com/zhayujie/CowAgent/commit/8b45d6c)
### QQ 通道
新增 QQ 官方机器人（`qq`）通道，支持文本和图片消息的接收与回复，支持私聊和群聊场景。
接入文档参考：[QQ机器人接入](https://docs.cowagent.ai/channels/qq)。
相关提交：[005a0e1](https://github.com/zhayujie/CowAgent/commit/005a0e1), [a4d54f5](https://github.com/zhayujie/CowAgent/commit/a4d54f5)
## 🖥️ Web 控制台支持文件输入和处理
Web 控制台对话界面支持文件和图片上传，可直接发送文件给 Agent 进行处理。同时 Read 工具新增对 Office 文档（Word、Excel、PPT）的解析能力。
相关提交：[30c6d9b](https://github.com/zhayujie/CowAgent/commit/30c6d9b)
## 🤖 新增模型
- **GPT-5.4 系列**：新增 `gpt-5.4`、`gpt-5.4-mini`、`gpt-5.4-nano` 模型支持 ([1623deb](https://github.com/zhayujie/CowAgent/commit/1623deb))
- **Gemini 3.1 Flash Lite Preview**：新增 `gemini-3.1-flash-lite-preview` 模型支持 ([ba915f2](https://github.com/zhayujie/CowAgent/commit/ba915f2))
## 💰 Coding Plan 支持
新增各厂商 Coding Plan（编程包月套餐）的接入支持，通过 OpenAI 兼容方式统一接入。目前已支持阿里云、MiniMax、智谱 GLM、Kimi、火山引擎等厂商。
详细配置参考 [Coding Plan 文档](https://docs.cowagent.ai/models/coding-plan)。
## 🧠 记忆系统升级
记忆写入（Memory Flush）升级：
- 使用 LLM 对超出上下文窗口的对话内容进行智能摘要，生成精炼的每日记忆条目
- 摘要在后台线程异步执行，不阻塞回复
- 优化上下文批量裁剪策略，降低冲刷频率
- 新增每日定时冲刷兜底机制，避免低活跃场景下记忆丢失
- 修复上下文记忆丢失问题
相关提交：[022c13f](https://github.com/zhayujie/CowAgent/commit/022c13f), [c116235](https://github.com/zhayujie/CowAgent/commit/c116235)
## 🔧 工具重构
- **图片识别**：将图片识别（Image Vision）从 Skill 重构为内置 Tool，新增独立的图片视觉提供方（Vision Provider）配置，提升稳定性和可维护性 ([a50fafa](https://github.com/zhayujie/CowAgent/commit/a50fafa), [3b8b562](https://github.com/zhayujie/CowAgent/commit/3b8b562))
- **网页抓取**：将网页抓取（Web Fetch）从 Skill 重构为内置 Tool，支持远程文档文件（PDF、Word、Excel、PPT）的下载和解析 ([ccb9030](https://github.com/zhayujie/CowAgent/commit/ccb9030), [fa61744](https://github.com/zhayujie/CowAgent/commit/fa61744))
## 🐳 Docker 部署优化
- **配置模板对齐**：`docker-compose.yml` 环境变量与 `config-template.json` 对齐，补充完整的模型 API Key 和 Agent 等配置项
- **Web 控制台端口映射**：新增 `9899` 端口映射，Docker 部署后可通过浏览器访问 Web 控制台
- **配置热更新**：各模型 Bot 的 API Key 和 API Base 改为实时读取，通过 Web 控制台修改配置后无需重启即可生效
- **工作空间持久化**：新增 `./cow` Volume 挂载，Agent 工作空间数据（记忆、人格、技能等）持久化到宿主机，容器重建或升级不丢失
## ⚡ 性能优化
- **启动加速**：飞书通道采用懒加载方式导入依赖，避免 4-10 秒的启动延迟 ([924dc79](https://github.com/zhayujie/CowAgent/commit/924dc79))
- **通道稳定性**：优化通道连接稳定性，支持通道配置通过环境变量设置 ([f1c04bc](https://github.com/zhayujie/CowAgent/commit/f1c04bc), [46d97fd](https://github.com/zhayujie/CowAgent/commit/46d97fd))
## 🐛 问题修复
- **bot_type 配置**：修复 Agent 模式下 `bot_type` 配置传递问题 ([#2691](https://github.com/zhayujie/CowAgent/pull/2691)) Thanks [@Weikjssss](https://github.com/Weikjssss)
- **bot_type 优先级**：调整 Agent 模式下 `bot_type` 的解析优先级 ([#2692](https://github.com/zhayujie/CowAgent/pull/2692)) Thanks [@6vision](https://github.com/6vision)
- **智谱模型配置**：修复智谱 `bot_type` 命名、Web 控制台持久化及正则转义问题 ([#2693](https://github.com/zhayujie/CowAgent/pull/2693)) Thanks [@6vision](https://github.com/6vision)
- **OpenAI 兼容层**：使用 `openai_compat` 层统一错误处理 ([#2688](https://github.com/zhayujie/CowAgent/pull/2688)) Thanks [@JasonOA888](https://github.com/JasonOA888)
- **OpenAI 兼容迁移**：完成所有模型 Bot 的 `openai_compat` 迁移 ([#2689](https://github.com/zhayujie/CowAgent/pull/2689))
- **Gemini 工具调用**：修复 Gemini 模型的工具调用匹配问题 ([eda82ba](https://github.com/zhayujie/CowAgent/commit/eda82ba))
- **会话并发**：修复会话并发场景下的竞态条件问题 ([9879878](https://github.com/zhayujie/CowAgent/commit/9879878))
- **历史消息恢复**：修复历史会话消息不完整问题，仅恢复 user/assistant 文本消息，剥离工具调用 ([b788a3d](https://github.com/zhayujie/CowAgent/commit/b788a3d), [a33ce97](https://github.com/zhayujie/CowAgent/commit/a33ce97))
- **飞书群聊**：移除飞书群聊场景下对 `bot_name` 的依赖 ([b641bff](https://github.com/zhayujie/CowAgent/commit/b641bff))
- **Safari 兼容**：修复 Safari 浏览器 IME 回车键误触发消息发送问题 ([0687916](https://github.com/zhayujie/CowAgent/commit/0687916))
- **Windows 兼容**：修复 Windows 下 bash 风格 `$VAR` 环境变量转换为 `%VAR%` 的问题 ([7c67513](https://github.com/zhayujie/CowAgent/commit/7c67513))
- **MiniMax 参数**：增加 MiniMax 模型的 `max_tokens` 限制 ([1767413](https://github.com/zhayujie/CowAgent/commit/1767413))
- **.gitignore 更新**：添加 Python 目录忽略规则 ([#2683](https://github.com/zhayujie/CowAgent/pull/2683)) Thanks [@pelioo](https://github.com/pelioo)
- **AGENT.md 主动演进**：优化系统提示词中对 AGENT.md 的更新引导，从被动的"用户修改时更新"改为主动识别对话中的性格、风格变化并自动更新
## 📦 升级方式
源码部署可执行 `./run.sh update` 一键升级，或手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/guide/upgrade)。
**发布日期**：2026.03.18 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.2...master)

51
docs/zh/releases/v2.0.4.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
title: v2.0.4
description: CowAgent 2.0.4 - 新增个人微信通道、新模型支持、日文文档、脚本重构及多项修复
---
## 🔌 新增个人微信通道
新增个人微信（`weixin`）通道，微信扫描二维码即可将 CowAgent 接入个人微信，支持以下功能：
- **消息收发**：支持文本、图片、文件、视频消息的接收与回复，支持语音消息接收和识别
- **扫码登录**：终端显示二维码，微信扫码确认即可登录，二维码过期自动刷新
- **凭证持久化**：登录凭证自动保存至 `~/.weixin_cow_credentials.json`，重启无需重新扫码
- **Session 自动重连**：Session 过期后自动清除旧凭证并重新发起扫码登录
- **Web 控制台接入**：支持在 Web 控制台中添加微信通道，扫码登录流程同步展示
- **Docker 和脚本支持**：`run.sh` 和 `docker-compose.yml` 均已适配微信通道
接入文档：[微信接入](https://docs.cowagent.ai/channels/weixin)。
相关提交：[ce89869](https://github.com/zhayujie/CowAgent/commit/ce89869)
## 🤖 新增模型
- **MiniMax-M2.7**：新增 MiniMax-M2.7 模型支持
- **GLM-5-Turbo**：新增智谱 glm-5-turbo 模型支持
相关提交：[9192f6f](https://github.com/zhayujie/CowAgent/commit/9192f6f)
## 🔧 脚本重构
- **run.sh 重构**：提取公共逻辑，精简脚本代码([49d8707](https://github.com/zhayujie/CowAgent/commit/49d8707))
- **可执行权限**：修复 `run.sh` 文件权限问题 ([652156e](https://github.com/zhayujie/CowAgent/commit/652156e))
- **PID 获取**：修复 `run.sh` 中进程 PID 获取错误的问题 ([9febb07](https://github.com/zhayujie/CowAgent/commit/9febb07))
## 🌍 文档更新
新增完整的日文文档，覆盖入门指南、通道接入、模型配置等主要章节。Thanks [@Ikko Ashimine](https://github.com/ikoamu)
相关提交：[5487c0b](https://github.com/zhayujie/CowAgent/commit/5487c0b)
## 🐛 问题修复
- **企微机器人兼容**：修复旧版 `websocket-client` 的兼容性问题，新增统一的 WebSocket 兼容层 ([bc7f627](https://github.com/zhayujie/CowAgent/commit/bc7f627))
- **消息自动修复**：增强消息协议的容错能力，自动修复格式异常的消息序列 ([b8b57e3](https://github.com/zhayujie/CowAgent/commit/b8b57e3))
- **飞书编码**：修复飞书通道消息和日志的编码问题 ([7d0e156](https://github.com/zhayujie/CowAgent/commit/7d0e156))
- **飞书配置**：移除 `run.sh` 中对 `feishu_bot_name` 的冗余依赖 ([1b5be1b](https://github.com/zhayujie/CowAgent/commit/1b5be1b))
## 📦 升级方式
源码部署可执行 `./run.sh update` 一键升级，或手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/guide/upgrade)。
**发布日期**：2026.03.22 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.3...master)

84
docs/zh/releases/v2.0.5.mdx Normal file
View File

@@ -0,0 +1,84 @@
---
title: v2.0.5
description: CowAgent 2.0.5 - Cow CLI、Skill Hub 开源、浏览器工具、企微扫码创建、DeepSeek 独立模块及多项优化
---
## 🖥️ Cow CLI 命令系统
新增 Cow CLI 命令系统，支持在终端和对话中执行命令，实现对 CowAgent 的全方位管理：
- **终端命令**：在系统终端中执行 `cow <命令>`，支持 `start`、`stop`、`restart`、`update`、`status`、`logs` 等服务管理操作
- **对话命令**：在对话中输入 `/<命令>` 或 `cow <命令>`，支持 `/help`、`/status`、`/config`、`/skill`、`/context`、`/logs`、`/version` 等
- **web控制台**：Web 控制台输入框输入 `/` 即可弹出指令菜单，支持方向键回溯历史输入
- **Windows 支持**：新增 PowerShell 一键安装脚本 `scripts/run.ps1`，同时支持 `cow` 命令
相关文档：[命令总览](https://docs.cowagent.ai/cli)
<img src="https://cdn.link-ai.tech/doc/20260401114549.png" width="750" />
## 🧩 Cow Skill Hub 开源
[Cow Skill Hub](https://skills.cowagent.ai)（技能广场）正式开源并上线，提供 AI Agent 技能的浏览、搜索、安装和发布，汇集精选技能、社区贡献技能、三方技能：
- **一键安装**：在对话中 `/skill install <名称>` 或终端 `cow skill install <名称>` 一键安装
- **多来源支持**：支持安装 Skill Hub、GitHub、ClawHub、LinkAI 上的全部技能，支持 GitHub 批量安装和子目录指定
- **技能搜索**：`/skill search` 和 `/skill list --remote` 浏览和搜索技能广场
- **技能发布**：通过 [skills.cowagent.ai/submit](https://skills.cowagent.ai/submit) 提交自己的技能
- **镜像加速**：支持 Skill Hub 镜像加速，国内环境下载更流畅
Skill Hub 开源仓库：[cow-skill-hub](https://github.com/zhayujie/cow-skill-hub)。
相关文档：[技能广场](https://docs.cowagent.ai/skills/hub)、[安装技能](https://docs.cowagent.ai/skills/install)
<img src="https://cdn.link-ai.tech/doc/20260401110103.png" width="750" />
## 🌐 新增浏览器工具
新增 Browser 工具，Agent 可控制浏览器访问和操作网页：
- **网页导航与交互**：支持 `navigate`、`click`、`fill`、`select`、`scroll`、`press` 等操作
- **页面快照**：使用精简 DOM 快照技术，让 Agent 高效理解页面结构，导航后自动快照
- **截图能力**：支持页面截图保存到工作区
- **JavaScript 执行**：支持在页面中执行自定义脚本
- **CLI 安装**：通过 `cow install-browser` 一键安装浏览器及依赖，自动适配系统环境
- **Docker 支持**：Docker 镜像已内置浏览器安装支持
相关文档：[浏览器工具](https://docs.cowagent.ai/tools/browser)。
<img src="https://cdn.link-ai.tech/doc/20260401115728.png" width="750" />
## 🤖 企微智能机器人扫码创建
企业微信智能机器人通道新增扫码一键创建功能：
- **Web 控制台扫码**：在 Web 控制台通道页面，选择「扫码接入」模式，使用企业微信扫码即可自动创建并接入智能机器人，无需手动到企业微信后台配置
- **手动模式保留**：同时保留「手动填写」模式，可输入已有的 Bot ID 和 Secret 接入
- **流式推送优化**：增加推送节流，避免 WebSocket 拥塞
相关文档：[企微智能机器人接入](https://docs.cowagent.ai/channels/wecom-bot)。
相关提交：[#2735](https://github.com/zhayujie/CowAgent/pull/2735)
Thanks [@WecomTeam](https://github.com/WecomTeam)
## 🐛 其他优化与修复
- **DeepSeek 独立模块**：新增独立的 DeepSeek Bot 模块，支持 `deepseek_api_key` 专属配置，无需再通过 OpenAI 兼容方式接入（[#2719](https://github.com/zhayujie/CowAgent/pull/2719)）。Thanks [@6vision](https://github.com/6vision)
- **Web 控制台优化**：新增斜杠指令菜单和输入历史回溯，新增模型选项，优化移动端适配（[#2731](https://github.com/zhayujie/CowAgent/pull/2731)）。Thanks [@zkjqd](https://github.com/zkjqd)
- **上下文丢失**：修复上下文裁剪后丢失的问题 ([393f0c0](https://github.com/zhayujie/CowAgent/commit/393f0c0))
- **系统提示词**：修复系统提示词未在每轮重建的问题 ([13f5fde](https://github.com/zhayujie/CowAgent/commit/13f5fde))
- **Agent 响应**：去除 Agent 响应首尾空白字符 ([f890318](https://github.com/zhayujie/CowAgent/commit/f890318))
- **视觉压缩**：优化视觉图片压缩策略 ([22b8ca0](https://github.com/zhayujie/CowAgent/commit/22b8ca0))
- **Gemini 模型**：修复 GoogleGeminiBot 缺少 model 属性的问题（[#2716](https://github.com/zhayujie/CowAgent/pull/2716)）。Thanks [@cowagent](https://github.com/cowagent)
- **微信通道**：修复文件发送失败、文件名丢失等问题 ([6d9b7ba](https://github.com/zhayujie/CowAgent/commit/6d9b7ba)、[baf66a1](https://github.com/zhayujie/CowAgent/commit/baf66a1)、[45faa9c](https://github.com/zhayujie/CowAgent/commit/45faa9c))
- **Docker 优化**：修复卷权限问题，精简镜像体积 ([3eb8348](https://github.com/zhayujie/CowAgent/commit/3eb8348)、[4470d4c](https://github.com/zhayujie/CowAgent/commit/4470d4c))
- **README 排版**：优化中英文排版空格（[#2723](https://github.com/zhayujie/CowAgent/pull/2723)）。Thanks [@Xiaozhou345](https://github.com/Xiaozhou345)
- **安全修复**：修复 Memory Content路径遍历风险，Thanks [@August829](https://github.com/August829)
## 📦 升级方式
源码部署可执行 `cow update` 或 `./run.sh update` 一键升级，或手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/guide/upgrade)。
**发布日期**：2026.04.01 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.4...master)

83
docs/zh/releases/v2.0.6.mdx Normal file
View File

@@ -0,0 +1,83 @@
---
title: v2.0.6
description: CowAgent 2.0.6 - 知识库系统、梦境记忆蒸馏、上下文智能压缩、Web 控制台多会话及多项优化
---
## 项目正式更名为 CowAgent
项目仓库正式从 `chatgpt-on-wechat` 更名为 **CowAgent**，演进为功能完备的 AI Agent 助理。
- 新地址：[github.com/zhayujie/CowAgent](https://github.com/zhayujie/CowAgent)，旧地址 GitHub 会自动重定向
- CLI 命令、配置文件、文档链接均保持兼容，无需额外操作
## 📚 知识库系统
新增个人知识库系统，Agent 可自主构建和维护结构化知识，并在对话中按需检索引用。
- **索引驱动的自组织结构**：知识库采用 `knowledge/` 目录，按分类自动组织，每个知识页面为独立的 Markdown 文件
- **自动写入**：向 Agent 发送文件、链接等知识，或在讨论中识别到有价值的知识时，自动创建或更新知识页面
- **混合检索**：支持关键词全文搜索和向量语义检索，在对话中按需加载相关知识
- **可视化**：支持文件树浏览和知识图谱可视化，文档内链接可直接跳转查看
- **命令管理**：`/knowledge` 查看统计、`/knowledge list` 查看目录结构、`/knowledge on|off` 开关知识库
<img src="https://cdn.link-ai.tech/doc/20260413105435.png" width="750" />
相关文档：[知识库](https://docs.cowagent.ai/knowledge)
Inspired by Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
## 🌙 梦境记忆蒸馏（Deep Dream）
全新的记忆整理机制，每日自动将分散的对话记忆蒸馏为精炼的长期记忆：
- **三层记忆流转**：对话上下文（短期）→ 天级记忆（中期）→ MEMORY.md（长期），形成完整的记忆生命周期
- **自动蒸馏**：每日 23:55 定时执行，读取当天天级记忆和 MEMORY.md，通过 LLM 进行去重、合并、修剪，输出精炼的新版 MEMORY.md
- **梦境日记**：每次蒸馏生成一篇叙事风格的梦境日记，记录整理过程的发现和洞察，存储在 `memory/dreams/` 目录
- **手动触发**：支持 `/memory dream [N]` 手动触发，可指定整理天数（默认 3 天，最大 30 天），完成后在对话中通知结果
- **Web 控制台**：记忆管理页面新增「梦境日记」tab，可浏览和查看所有梦境日记
相关文档：[梦境蒸馏](https://docs.cowagent.ai/memory/deep-dream)
<img src="https://cdn.link-ai.tech/doc/20260414120158.png" width="750" />
## 🧠 上下文智能压缩
上下文超出限制时将裁剪的部分通过 LLM 总结后异步注入，保持对话连贯性：
- **LLM 异步摘要**：裁剪的消息由 LLM 总结为关键信息，同时写入天级记忆文件和注入保留的上下文
- **多模型兼容**：优先使用主模型进行摘要，兼容 Claude、OpenAI、MiniMax 等不同模型的消息格式要求
相关文档：[短期记忆](https://docs.cowagent.ai/memory/context)
## 💬 Web 控制台升级
Web 控制台多项功能增强：
- **多会话管理**：支持创建和切换多个独立会话，侧边栏展示会话列表，支持会话标题自动生成和手动编辑
- **密码保护**：支持为控制台设置登录密码，可通过 `web_console_password` 配置项控制
- **深度思考**：支持在 Web 端展示模型的思考过程，可通过`enable_thinking` 配置项控制
- **定时推送**：支持定时任务结果推送到 Web 控制台
- **消息复制**：AI 回复支持一键复制原始 Markdown 内容
## 🤖 模型相关
- **视觉识别优化**：图片识别工具优先使用主模型，支持多模型厂商自动降级。相关文档：[视觉工具](https://docs.cowagent.ai/tools/vision)
- **MiniMax 新模型**：新增 MiniMax-M2.7-highspeed 模型和 MiniMax TTS 语音合成支持。Thanks @octo-patch
- **通义千问**：新增 qwen3.6-plus 模型支持
## 🐛 其他优化与修复
- **记忆提示词优化**：`MEMORY.md` 默认注入系统提示词，精细化记忆检索和写入的触发条件，增强主动写入能力
- **系统提示词**：优化系统提示词的风格和语气引导
- **浏览器工具**：增强隐式交互元素检测
- **文件发送**：修复通用文件类型（tar.gz、zip 等）未能正确发送的问题。Thanks @6vision
- **macOS 兼容**：修复网络预检超时兼容性问题。Thanks @Moliang Zhou
- **Windows 兼容**：修复 Windows 下 PowerShell 兼容性、进程更新、终端编码等多项问题
- **Python 3.13+**：修复 Python 3.13 及以上版本缺少 `legacy-cgi` 依赖的问题
- **个人微信**：更新个人微信通道版本
## 📦 升级方式
源码部署可执行 `cow update` 或 `./run.sh update` 一键升级，或手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/guide/upgrade)。
**发布日期**：2026.04.14 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.5...master)

64
docs/zh/releases/v2.0.7.mdx Normal file
View File

@@ -0,0 +1,64 @@
---
title: v2.0.7
description: CowAgent 2.0.7 - 图像生成技能（六厂商自动路由）、新模型支持、知识库增强、Web 控制台优化及多项修复
---
## 🎨 图像生成技能
新增图像生成内置技能，支持文生图、图生图、多图融合，支持 `GPT-Image-2`、`Nano Banana` 等多种模型：
- **自动路由**：支持六种模型厂商自动切换，OpenAI (GPT-Image-2) → Gemini (Nano Banana) → Seedream (火山方舟) → Qwen (百炼) → MiniMax → LinkAI
- **开箱即用**：配置 API Key 即可使用，无需手动指定模型。也支持在对话中指定特定模型
- **灵活控制**：支持 `quality`（画质）、`size`（分辨率，512/1K~4K）、`aspect_ratio`（宽高比）等参数，各厂商自动适配有效值
- **图片编辑**：传入已有图片即可进行编辑、风格迁移、多图融合
- **Skill 级配置**：支持通过 `config.json` 中的 `skills.image-generation.model` 固定默认模型
相关文档：[图像生成技能](https://docs.cowagent.ai/skills/image-generation)
## 🤖 新模型支持
- **Kimi K2.6**：新增 `kimi-k2.6` 模型支持
- **Claude Opus 4.7**：新增 `claude-opus-4-7` 模型支持
- **GLM 5.1**：新增 `glm-5.1` 模型支持
- **Kimi Coding Plan**：支持 Kimi Coding Plan 模式
- **自定义模型厂商**：新增[自定义模型](https://docs.cowagent.ai/models/custom)提供方配置，方便接入本地模型及更多厂商
## 📚 知识库增强
- **嵌套目录支持**：知识库列表和展示支持多级嵌套目录
- **根级文件展示**：知识树中显示根目录下的 `index.md`、`log.md` 等文件
- **空状态统计修复**：排除根级文件对知识库统计的干扰，正确保持空状态
## 🌙 梦境记忆优化
- **结构化组织**：梦境记忆文件按日期自动归档，目录结构更清晰
- **定时抖动**：每日定时触发增加随机抖动，避免集群场景下的并发冲突
## 🛠 技能系统改进
- **技能管理刷新**：`/skill` 命令执行后自动加载最新技能，确保状态同步
- **安装来源扩展**：技能安装支持多种来源格式（URL、zip、本地文件等）
## 💬 Web 控制台优化
- **智能自动滚动**：优化聊天窗口滚动逻辑，用户手动翻阅时不再强制跳到底部 Thanks @colin2060
- **移动端适配**：侧边栏默认隐藏，支持点击遮罩关闭
- **图片预览去重**：修复同一消息中图片重复渲染的问题
- **推理内容截断**：深度思考内容超出阶段，解决前端卡顿问题
- **会话标题修复**：修复标题自动生成的回退逻辑
## 🐛 其他修复
- **Gemini 修复**：修复 Gemini tool call 不返回结果的问题
- **Agent 重试**：空响应重试时不再丢弃 tool_calls
- **Docker 环境变量**：修复 Docker 环境下更新配置后环境变量未同步的问题 Thanks @sunboy0523
- **Python 3.7 兼容**：延迟导入 `Literal` 以兼容 Python 3.7
- **模型切换通知**：修复切换模型后 bot_type 变更通知未显示的问题。Thanks @6vision
- **配置命令增强**：`/config` 支持设置 `enable_thinking`
## 📦 升级方式
源码部署可执行 `cow update` 或 `./run.sh update` 一键升级，或手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/guide/upgrade)。
**发布日期**：2026.04.22 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.6...2.0.7)

63
docs/zh/releases/v2.0.8.mdx Normal file
View File

@@ -0,0 +1,63 @@
---
title: v2.0.8
description: CowAgent 2.0.8 - 飞书渠道全面升级（语音、流式打字机、一键扫码接入）、DeepSeek V4 / 百度千帆支持、定时任务工具优化
---
## 🪶 飞书渠道全面升级
### 1. 一键扫码创建飞书应用
不再需要手动到飞书开放平台建应用、填权限和事件订阅。Web 控制台和命令行启动时若未配置 `feishu_app_id`，会自动展示扫码入口，飞书扫码授权后自动创建机器人并回填配置，开箱即用。
相关文档：[飞书渠道](https://docs.cowagent.ai/channels/feishu)
### 2. 语音消息收发
支持接收用户发送的飞书语音消息并自动转文本，回复也可走 TTS 以语音形式发出。同时优化了中文短语音的识别准确度。
### 3. 流式打字机回复
接入飞书 CardKit 流式卡片，**默认开启**，体验对齐 Web 端：
- 多轮 Agent 场景下中间过场消息与最终回复分卡呈现
- 针对 DeepSeek 等高频输出模型做了专门优化，速度与 Web 端持平
- 不支持时自动回退为普通文本回复，无需手动配置
- 要求飞书客户端 ≥ 7.20
飞书语音消息收发与流式打字机的基础能力来自社区贡献 #2791 Thanks @yangluxin613
## 🤖 新模型支持
- **DeepSeek V4 系列**：新增 `deepseek-v4-pro` / `deepseek-v4-flash`，并将默认模型切换为 `deepseek-v4-flash`
- **思考模型开关统一**：DeepSeek V4、Qwen3 等思考模型的开关行为对齐到 `enable_thinking`
- **百度千帆模型接入**：新增百度千帆厂商，支持 `ernie-5.0`、`ernie-4.5-turbo-128k` 等模型，并支持图像识别工具，相关文档查看 [百度千帆](https://docs.cowagent.ai/models/qianfan)。#2790 Thanks @jimmyzhuu
- **新增有道翻译**：`translate` 模块新增有道翻译支持 #2797 Thanks @Zmjjeff7
## 🛠 OpenAI 客户端重构
- **去 SDK 依赖**：OpenAI Bot 改为原生 HTTP 实现，启动更轻、依赖冲突更少
- **Web 控制台提示**：模型配置 API Base 输入框加入版本路径占位提示
## ⏰ 定时任务记忆增强
- **任务结果可被追问**：定时任务的执行结果自动注入到接收方的会话历史中，下一轮对话可直接追问，无需重新交代上下文 Thanks @huangrichao2020
- **不污染长期记忆**：注入的调度对话不会被纳入每日梦境记忆汇总，避免高频任务把记忆刷满
- **避免越跑越慢**：调度任务自己的上下文长度自动控制在合理范围内，长期反复执行也不会越积越大、拖慢响应
## 🔧 工具与安全
- **图像识别模型**：让 `tools.vision.model` 配置真正生效，未配置时自动 fallback #2792 Thanks CNXudiandian
- **Bash 安全确认**：仅对工作区外的破坏性删除做二次确认，工作区内常规操作不再打扰
## 🐛 其他修复
- 修复 Deep Dream 在多实例场景下重复触发
- 修复 DeepSeek 多轮对话中部分历史轮次缺失 `reasoning_content`
## 📦 升级方式
源码部署可执行 `cow update` 或 `./run.sh update` 一键升级，或手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/guide/upgrade)。
> ⚠️ 飞书一键创建应用依赖 `lark-oapi>=1.5.5`，`cow update` 会自动拉取；手动部署请确保依赖已更新。
**发布日期**：2026.05.06 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.7...2.0.8)

65
docs/zh/releases/v2.0.9.mdx Normal file
View File

@@ -0,0 +1,65 @@
---
title: v2.0.9
description: CowAgent 2.0.9 - 新增模型管理、MCP 协议支持、浏览器登录态持久化、新模型接入
---
## 🖥️ 新增模型管理
Web 控制台新增「模型」页面，按 **模型厂商 + 模型能力** 进行管理，支持对话、图像、语音、向量模型和搜索能力的配置：
- **多厂商配置**：所有厂商的 API Key / API Base 在顶部统一维护，下方所有能力立即生效，无需重复填写
- **图像模型**：图像理解与图像生成均可独立选择厂商和模型，未指定时跟随主模型自动选择
- **语音模型**：语音识别和合成可独立配置，新增千问、智谱 ASR/TTS 模型
- **向量模型**：支持配置 Embedding 模型（用于记忆及知识库检索），新增支持 OpenAI、通义、豆包、智谱等；切换模型后需执行 `/memory rebuild-index` 在线重建索引
- **搜索能力**：联网搜索能力升级，支持博查、百度、智谱等多个厂商，自动模式下 Agent 可综合多来源搜索结果进行深度研究
相关文档：[模型概览](https://docs.cowagent.ai/models)
<img width="720" alt="20260522113305" src="https://cdn.link-ai.tech/doc/20260522113305.png" />
## 🧩 MCP 协议支持
支持 **MCP（Model Context Protocol）** 协议，从固定工具集扩展为开放可插拔的工具生态，任何兼容 MCP 协议的服务均可作为工具直接接入 Agent。
- 原生 JSON-RPC 实现，零额外依赖，同时支持 `stdio` 和 `sse` 两种传输
- 兼容 Claude Desktop / Cursor 等主流风格的 `mcpServers` 配置，优先读取 `~/cow/mcp.json`
相关文档：[MCP 工具](https://docs.cowagent.ai/tools/mcp)。Thanks @yangluxin613 (#2801)
## 🌐 浏览器登录态持久化
针对需要登录、有反爬机制的网站，浏览器工具支持登录一次后长期复用登录态，并允许接入用户自己的真实 Chrome 以通过指纹检测：
- **持久化用户配置（默认）**：默认使用 `~/.cow/browser_profile` 作为浏览器用户目录，登录一次后下次自动复用登录态
- **CDP 模式**：通过 `tools.browser.cdp_endpoint` 接管真实 Chrome 浏览器，享有完整浏览器权限
相关文档：[浏览器工具](https://docs.cowagent.ai/tools/browser)。Thanks @leafmove (#2809)
## 🤖 模型新增与优化
- **模型新增**：`gpt-5.5`、`gemini-3.5-flash`、`qwen3.7-max`、`ernie-5.1`
- **模型优化**：DeepSeek V4 支持 `reasoning_effort` 思考深度参数；修复 MiMo 等思考模型通过 OpenAI 兼容协议接入的问题
## 🔒 部署与安全
- **默认本机访问**：Web 控制台 `web_host` 配置默认绑定 `127.0.0.1`，服务器部署时可手动设置为 `0.0.0.0` 并设置密码。Thanks @August829、@yidaozhongqing、@YLChen-007、@icysun
- **前端资源完全本地化**：第三方 CSS / JS 全部本地分发，离线 / 内网环境也能正常加载控制台。Thanks @gitlayzer (#2816)
## 🛠 体验优化与修复
- **TTS 适配更多通道**：Web对话、个人微信、飞书、钉钉、企微智能机器人均已支持回复语音，详情查看 [通道概览](https://docs.cowagent.ai/channels)
- **日志面板增强**：根据日志等级差异化高亮展示、支持根据等级筛选。Thanks @yangluxin613 (#2807)
- **Web 控制台自动启动**：程序启动后自动打开 Web 控制台。Thanks @yangluxin613 (#2804)
- **Ctrl+C 干净退出**：不再打印一长串 `KeyboardInterrupt` 堆栈。Thanks @yangluxin613 (#2806)
- **文件夹上传**：Web 端支持目录上传，路径校验适配 Windows。Thanks @TryToMakeUsBetter (#2814)
- 修复定时任务在某些情况下重复执行的问题。Thanks @CNXudiandian (#2820)
- 修复定时任务带时区时单次任务不触发的问题。Thanks @AethericSpace
- 修复执行失败的工具调用在页面刷新后不显示的问题。Thanks @a1094174619 (#2822)
- 修复企微机器人消息中包含非法控制字符导致投递失败的问题。Thanks @Jacques-Zhao (#2810)
## 📦 升级方式
源码部署可执行 `cow update` 一键升级，或手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/guide/upgrade)。
**发布日期**：2026.05.22 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.0.8...2.0.9)

58
docs/zh/skills/create.mdx Normal file
View File

@@ -0,0 +1,58 @@
---
title: 创造技能
description: 通过对话创建自定义技能
---
CowAgent 内置了 Skill Creator，可以通过自然语言对话快速创建、安装或更新技能。
## 使用方式
直接在对话中描述你想要的技能，Agent 会自动完成创建：
- 将工作流程固化为技能："帮我把这个部署流程创建为一个技能"
- 对接第三方 API："根据这个接口文档创建一个技能"
- 安装远程技能："帮我安装 xxx 技能"
## 创建流程
1. 告诉 Agent 你想创建的技能功能
2. Agent 自动生成 `SKILL.md` 说明文件和运行脚本
3. 技能保存到工作空间的 `~/cow/skills/` 目录
4. 后续对话中 Agent 会自动识别并使用该技能
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202202247.png" width="800" />
</Frame>
## SKILL.md 格式
创建的技能遵循标准的 SKILL.md 格式：
```markdown
---
name: my-skill
description: Brief description of the skill
metadata:
emoji: 🔧
requires:
bins: ["curl"]
env: ["MY_API_KEY"]
primaryEnv: "MY_API_KEY"
---
# My Skill
Detailed instructions...
```
| 字段 | 说明 |
| --- | --- |
| `name` | 技能名称，需与目录名一致 |
| `description` | 技能描述，Agent 据此决定是否调用 |
| `metadata.requires.bins` | 依赖的系统命令 |
| `metadata.requires.env` | 依赖的环境变量 |
| `metadata.always` | 是否始终加载（默认 false） |
<Tip>
详细开发文档可参考 [Skill Creator 说明](https://github.com/zhayujie/CowAgent/blob/master/skills/skill-creator/SKILL.md)。
</Tip>

65
docs/zh/skills/hub.mdx Normal file
View File

@@ -0,0 +1,65 @@
---
title: 技能广场
description: 浏览、搜索和安装 AI Agent 技能
---
[Cow Skill Hub](https://skills.cowagent.ai/) 是开源的 AI Agent 技能广场，汇集了官方推荐、社区贡献和第三方平台（GitHub、ClawHub 等）的技能。
开源仓库：[github.com/zhayujie/cow-skill-hub](https://github.com/zhayujie/cow-skill-hub)
<img src="https://cdn.link-ai.tech/doc/20260401110103.png" width="800" />
## 功能
- **浏览技能**：按类别（推荐 / 社区 / 第三方）和标签筛选
- **搜索技能**：按名称或描述搜索
- **查看详情**：查看技能文档、文件内容、安装命令和依赖的环境变量
- **一键安装**：复制安装命令即可在 CowAgent 中使用
## 安装技能
在对话中或终端中执行安装命令：
<CodeGroup>
```text 对话
/skill install <name>
```
```bash 终端
cow skill install <name>
```
</CodeGroup>
也可以在对话中浏览技能广场：
```text
/skill list --remote
/skill search <关键词>
```
除了在列表中展示的精选技能，还可以通过 **CLI命令 + Skill Hub** 安装各种第三方技能（**GitHub、ClawHub、LinkAI、URL** 等）参考 [安装技能](/zh/skills/install)。
## 贡献技能
欢迎向技能广场提交你的技能：
1. 访问 [skills.cowagent.ai/submit](https://skills.cowagent.ai/submit)
2. 使用 GitHub 或 Google 账号登录
3. 上传包含 `SKILL.md` 的文件夹或 zip 包
4. 自动解析技能名称、显示名称和描述，可按需修改
5. 提交后将经过安全检查和审核后发布
<img src="https://cdn.link-ai.tech/doc/20260401111904.png" width="800" />
技能文件结构：
```
your-skill/
├── SKILL.md # 必须，放在根目录
├── scripts/ # 可选，运行脚本
└── resources/ # 可选，其他资源
```
<Tip>
技能基于 `SKILL.md` 文件构建，你也可以在技能详情页下载 SKILL.md，用于任何支持自定义指令的 Agent（如 OpenClaw、Cursor、Claude Code 等）。
</Tip>

98
docs/zh/skills/image-generation.mdx Normal file
View File

@@ -0,0 +1,98 @@
---
title: image-generation - 图像生成
description: 文生图 / 图生图 / 多图融合，支持多家厂商自动路由与回退
---
通用的图像生成与编辑技能，支持 OpenAI、Gemini、Seedream（火山方舟）、Qwen（百炼）、MiniMax、LinkAI 共六家厂商。配好任意一家的 Key 即可使用，配多家可享受自动回退。
## 支持的模型
| 厂商 | 模型 / 别名 | 特点 |
| --- | --- | --- |
| OpenAI | `gpt-image-2`、`gpt-image-1` | 通用文生图，高质量，支持 `quality` 控制画质 |
| Gemini Nano Banana | `nano-banana-2`、`nano-banana-pro`、`nano-banana` | 对应 `gemini-3.1-flash`、`gemini-3-pro`、`gemini-2.5-flash` 的图像版本 |
| Seedream（火山方舟） | `seedream-5.0-lite`、`seedream-4.5` | 原生 2K–4K，最多 14 张图融合 |
| Qwen（百炼） | `qwen-image-2.0`、`qwen-image-2.0-pro` | 擅长中文排版和图文融合 |
| MiniMax | `image-01` | 简单快速 |
| LinkAI | 任意模型 | 统一网关，作为兜底 |
## 模型选择
默认走「自动路由 + 失败回退」：
1. 按 `OpenAI → Gemini → Seedream → Qwen → MiniMax → LinkAI` 顺序选第一个已配置的厂商
2. 遇到 401、模型未开通、网络异常等错误时，自动切到下一家
3. 用户在对话里指定模型时（如「用 seedream 画一只猫」），对应厂商会被提到最前优先尝试
如需固定使用某个模型：
```json
{
"skills": {
"image-generation": {
"model": "seedream-5.0-lite"
}
}
}
```
## 配置 API Key
<Tip>
推荐通过 [Web 控制台](/zh/channels/web) 的「模型管理」页面配置，配好的对话模型 Key 会被图像生成技能自动复用，无需重复配置。也可手动编辑配置文件或在对话中通过 `env_config` 工具临时设置。
</Tip>
凭证统一复用主模型厂商的 Key：
| 字段 | 对应厂商 |
| --- | --- |
| `openai_api_key` | OpenAI |
| `gemini_api_key` | Gemini |
| `ark_api_key` | 火山方舟（Seedream） |
| `dashscope_api_key` | 阿里百炼（Qwen） |
| `minimax_api_key` | MiniMax |
| `linkai_api_key` | LinkAI |
## 开启和关闭
技能会根据 API Key 自动调整状态：
- **已配置 Key**：Agent 收到画图请求时直接调用
- **未配置 Key**：技能仍会出现在上下文中（标记为「需要配置」），Agent 会引导用户去配 Key
如需手动控制：
```text
/skill disable image-generation # 关闭
/skill enable image-generation # 重新开启
```
终端等价命令：`cow skill disable image-generation` / `cow skill enable image-generation`。
## 参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `prompt` | string | 是 | — | 图像描述 |
| `image_url` | string / list | 否 | null | 编辑用的输入图，本地路径或 URL；传列表为多图融合 |
| `quality` | string | 否 | auto | `low` / `medium` / `high`，仅部分厂商支持 |
| `size` | string | 否 | auto | `512` / `1K` / `2K` / `3K` / `4K`，或像素值如 `1024x1024` |
| `aspect_ratio` | string | 否 | null | `1:1` / `3:2` / `2:3` / `16:9` / `9:16` / `21:9`；Gemini 还支持 `1:4` / `4:1` / `1:8` / `8:1` |
<Warning>
**质量越高、分辨率越大，耗时和成本越高。** 日常对话用默认（`auto`）或 `quality=low` + `size=1K` 即可，约 20 秒出图；做海报或明确要高清时再上 `high` + `2K/4K`，可能需要 1–5 分钟。
</Warning>
## 常见用法
- **文生图**：根据描述生成插画、海报、图标、头像、分镜图等
- **图生图**：在已有图片上改风格、换元素、加装饰、加文字等
- **多图融合**：把多张参考图合成一张（换装、角色合影等）
<Note>
- bash 超时建议设 600 秒：单厂商 HTTP 超时 300 秒，脚本可能依次尝试多家
- 输入图片自动压缩到 4MB 以内、最长边不超过 4096px
- Gemini / Seedream / Qwen / MiniMax 不支持 `quality` 参数
- Seedream 默认出 2K 图；`seedream-5.0-lite` 支持到 3K，`seedream-4.5` 支持到 4K
</Note>

65
docs/zh/skills/index.mdx Normal file
View File

@@ -0,0 +1,65 @@
---
title: 技能概览
description: CowAgent 技能系统介绍
---
技能（Skill）为 Agent 提供无限的扩展性。每个 Skill 由说明文件（`SKILL.md`）、运行脚本（可选）、资源（可选）组成，描述如何完成特定类型的任务。
Skill 与 Tool 的区别：Tool 是由代码实现的原子操作（如读写文件、执行命令），Skill 则是基于说明文件的高级工作流，可以组合调用多个 Tool 来完成复杂任务。
## 获取技能
CowAgent 提供多种方式获取技能：
- [Cow 技能广场](https://skills.cowagent.ai/) — 在线浏览所有可用技能，或通过 `/skill list --remote` 在对话中浏览和安装
- **GitHub** — 直接从 GitHub 仓库安装，支持批量安装
- **ClawHub** — 通过 `/skill install clawhub:名称` 安装 ClawHub 上的技能 (4w+个)
- **LinkA** — 通过 `/skill install linkai:编码` 安装 LinkAI 上的公开资源和创建的知识库/数据库/工作流/插件等资源
- **URL** — 从 zip 压缩包或 SKILL.md 链接安装
- **对话创建** — 通过自然语言对话让 Agent 自动创建技能
详细安装方式参考 [安装技能](/zh/skills/install) 和 [技能管理命令](/zh/cli/skill)。也可以通过对话 [创建技能](/zh/skills/create)，或向 [Skill Hub](https://skills.cowagent.ai/submit) 贡献你的技能。
## 技能加载优先级
1. **工作空间技能**（最高）：`~/cow/skills/`
2. **项目内置技能**（最低）：`skills/`
同名技能按优先级覆盖。
## 技能文件结构
```
skills/
├── my-skill/
│ ├── SKILL.md # Skill description (frontmatter + instructions)
│ ├── scripts/ # Execution scripts (optional)
│ └── resources/ # Additional resources (optional)
```
### SKILL.md 格式
```markdown
---
name: my-skill
description: Brief description of the skill
metadata:
emoji: 🔧
requires:
bins: ["curl"]
env: ["MY_API_KEY"]
primaryEnv: "MY_API_KEY"
---
# My Skill
Detailed instructions...
```
| 字段 | 说明 |
| --- | --- |
| `name` | 技能名称，需与目录名一致 |
| `description` | 技能描述，Agent 据此决定是否调用 |
| `metadata.requires.bins` | 依赖的系统命令 |
| `metadata.requires.env` | 依赖的环境变量 |
| `metadata.always` | 是否始终加载（默认 false） |

66
docs/zh/skills/install.mdx Normal file
View File

@@ -0,0 +1,66 @@
---
title: 安装技能
description: 通过命令一键安装来自多种来源的技能
---
CowAgent 支持通过统一的 `install` 命令安装来自 [Cow 技能广场](https://skills.cowagent.ai/)、GitHub、ClawHub、LinkAI 以及任意 URL 上的技能。在对话中使用 `/skill install`，在终端中使用 `cow skill install`。
## 从Cow技能广场安装
访问 [skills.cowagent.ai](https://skills.cowagent.ai/) 浏览所有可用技能，找到想要的技能后直接安装，例如：
```text
/skill list --remote
/skill install pptx
```
## 从 GitHub 安装
> Github上的所有技能都可以直接安装，支持仓库级批量安装和指定子目录安装，例如：
```text
/skill install larksuite/cli
/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im
```
## 从 ClawHub 安装
[ClawHub](https://clawhub.ai/) 上的所有技能 (4w+个) 都可以一键安装，例如：
```text
/skill install clawhub:<name>
```
## 从 LinkAI 安装
[LinkAI](https://link-ai.tech/console) 上的所有公开资源 (1w+个应用/工作流/插件) ，以及自己创建的资源 (应用/工作流/知识库/数据库/插件) 都可以通过命令一键安装：
```text
/skill install linkai:<code>
```
> LinkAI平台上创建的所有应用、工作流、知识库、数据库、插件都有唯一的code，可在[控制台](https://link-ai.tech/console)各资源页面中进行获取并填写到命令中
## 从 URL 安装
支持 zip 压缩包和 SKILL.md 文件链接：
```text
/skill install https://cdn.link-ai.tech/skills/pptx.zip
/skill install https://example.com/path/to/SKILL.md
```
## 管理技能
```text
/skill list # 查看已安装技能
/skill info pptx # 查看技能详情
/skill enable pptx # 启用技能
/skill disable pptx # 禁用技能
/skill uninstall pptx # 卸载技能
```
<Tip>
以上所有命令在终端中使用时，将 `/skill` 替换为 `cow skill` 即可。完整命令说明参考 [技能管理命令](/zh/cli/skill)。
</Tip>

112
docs/zh/skills/knowledge-wiki.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: knowledge-wiki - 知识库
description: 维护本地结构化知识库，自动归档、分类和交叉引用
---
帮你把对话中产生的资料、灵感和零散笔记整理成结构化的本地知识库，自动维护索引和页面之间的交叉引用。
`knowledge-wiki` 在工作空间下维护一个 `knowledge/` 目录，相当于 Agent 的「外脑」。技能设置了 `always: true`，会**常驻上下文**，不需要任何外部依赖。
## 什么时候会触发
- 你分享了一篇文章、一份文档或一个 URL，想要沉淀下来
- 聊天过程中聊出了值得长期保留的结论
- 你想查一下之前积累过的知识
## 目录结构
```
knowledge/
├── index.md # 全局索引（必须维护）
├── log.md # 操作日志（只追加）
└── <category>/ # 分类子目录（按内容自由分组）
└── <slug>.md # 知识页（文件名用小写加中划线）
```
## 三个核心操作
### 1. 收录（Ingest）
你分享了一段资料时，Agent 会：
1. 读懂原文，提取关键信息
2. 按内容决定放到哪个分类下——先看 `index.md` 里有没有合适的分类，没有就新建一个
3. 生成知识页 `knowledge/<category>/<slug>.md`
4. 更新索引 `index.md` 和日志 `log.md`
### 2. 综合（Synthesize）
聊天中产生了新的结论或洞见时：
1. 在合适的分类下创建新知识页
2. 给相关的已有页面加上互相指向的链接
3. 更新索引和日志
### 3. 查询（Query）
你问到以前积累的知识时：
1. 先从 `index.md` 里找可能相关的页面
2. 用 `read` 工具打开具体页面
3. 需要时再用 `memory_search` 补充检索
4. 回答里会带上知识页的链接，方便你点过去看原文
## 知识页怎么写
```markdown
# 页面标题
> Source: <来源 URL 或简要说明>
正文内容。页面之间用相对路径链接：
[相关页](../category/related-page.md)
## 要点
- ...
## 相关页面
- [页面 A](../category/page-a.md) — 为什么相关
```
<Note>
- `> Source:` 用来记录这条知识的来源。有明确来源时一定要写
- 交叉引用很重要：创建或更新某页时，记得也去关联页面里补上反向链接
- **只链接已经存在的页面**。如果某个概念值得单独成页，先建好再加链接
</Note>
## 索引格式
`knowledge/index.md` 采用扁平列表，按分类分组，每个知识页占一行：
```markdown
# Knowledge Index
## 分类 A
- [页面标题](category-a/page-slug.md) — 一句话摘要
## 分类 B
- [页面标题](category-b/page-slug.md) — 一句话摘要
```
不用表格，不加 emoji。分类怎么起名、怎么组织都可以灵活调整。
## 日志格式
`knowledge/log.md` 只追加、不修改，最新的写在最下面：
```markdown
## [YYYY-MM-DD] ingest | 页面标题
## [YYYY-MM-DD] synthesize | 页面标题
```
## 写作约定
- **文件名**用小写加中划线，比如 `machine-learning.md`
- **一页只讲一件事**，需要关联的内容通过链接串起来
- **有了就更新，不要重复建页**
- **每次改完都要更新索引** `knowledge/index.md`
- **写精华别抄全文**，抓住要点就行
- **对话里引用知识页时用完整路径**，比如 `[标题](knowledge/<category>/<slug>.md)`。页面之间互相链接才用相对路径
- **基于知识页回答问题时附上链接**，方便深入查阅

180
docs/zh/skills/skill-creator.mdx Normal file
View File

@@ -0,0 +1,180 @@
---
title: skill-creator - 技能创建
description: 创建、安装、更新技能，规范 SKILL.md 写法与目录结构
---
`skill-creator` 是一个「元技能」，专门用来帮助 Agent 创建、安装和更新其他技能，确保所有技能的 `SKILL.md` 写法和目录结构保持一致。
## 什么时候会触发
- 用户想从 URL 或远程仓库安装一个技能
- 用户想从头创建一个全新的技能
- 需要升级或重构已有技能
## 技能是什么
简单来说，技能就是一份「可复用的说明书」加上可选的脚本和资源。它给 Agent 注入了某个领域的专业知识，让 Agent 在遇到对应任务时能像专家一样处理。
一个技能通常包含以下内容：
1. **专项工作流** — 某类任务的完整步骤
2. **工具用法** — 怎么调某种 API 或处理某种文件
3. **领域知识** — 团队约定、业务规则、数据结构之类
4. **附带资源** — 脚本、参考文档、模板等
<Note>
**核心原则：能省则省**。只写 Agent 自己想不到的内容，每加一行都要问自己：值不值得占这些 token？
</Note>
## 目录结构
```
skill-name/
├── SKILL.md # 必需：技能定义
│ ├── YAML frontmatter（必填 name / description）
│ └── Markdown 正文（说明 + 示例）
└── 可选资源
├── scripts/ # 可执行脚本（Python / Bash 等）
├── references/ # 内容较多的参考文档，Agent 按需读取
└── assets/ # 模板、图标等，会直接用在输出里
```
## SKILL.md 规范定义
SKILL.md 文件头部的 `frontmatter` 字段：
| 字段 | 说明 |
| --- | --- |
| `name` | 技能名，小写加中划线，必须和目录名一致 |
| `description` | **最关键的字段**。写清楚「这个技能干什么」和「什么情况下该用它」，Agent 看到这段来决定要不要调它。注意：所有触发相关的描述都放在这里，不要写到正文里 |
| `metadata.cowagent.requires.bins` | 系统里必须装了哪些命令行工具 |
| `metadata.cowagent.requires.env` | 需要哪些环境变量（全部满足才行） |
| `metadata.cowagent.requires.anyEnv` | 多个 API Key 满足一个就行 |
| `metadata.cowagent.requires.anyBins` | 多个工具满足一个就行 |
| `metadata.cowagent.always` | 设为 `true` 会始终加载，不检查依赖 |
| `metadata.cowagent.emoji` | 展示用的 emoji（可选） |
| `metadata.cowagent.os` | 限定系统，如 `["darwin", "linux"]` |
<Note>
`category` 字段不需要手写，系统会自动设成 `skill`。
</Note>
声明 API Key 依赖有两种写法：
```yaml
metadata:
cowagent:
requires:
env: ["MYAPI_KEY"] # 必须有
```
```yaml
metadata:
cowagent:
requires:
anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"] # 有一个就行
```
**技能会自动按依赖启禁用**：环境变量齐了就自动启用，缺了就自动禁用，不需要手动 `/skill enable`。
## 资源目录怎么用
| 目录 | 放什么 | 不要放 |
| --- | --- | --- |
| `scripts/` | 需要反复执行的代码，或需要确定性结果的脚本 | 纯演示用的代码片段 |
| `references/` | **超过 500 行**、SKILL.md 实在塞不下的大文档（比如完整的数据库 Schema） | 普通 API 文档、示例、教程 |
| `assets/` | 会出现在最终产物里的文件（模板、图标、样板代码等） | 说明性文档 |
<Warning>
**原则上所有内容都写在 `SKILL.md` 里**，只有确实放不下才拆到资源目录。
不要给技能加 `README.md`、`CHANGELOG.md`、`INSTALLATION_GUIDE.md` 之类的文件——全部放进 `SKILL.md`。资源目录里只放真正要跑的脚本或真正要用的素材。
</Warning>
## 安装外部技能
安装后最终落在 `<workspace>/skills/<name>/` 目录。
| 来源 | 怎么装 |
| --- | --- |
| URL（单文件） | curl / web_fetch 直接拉 |
| URL（zip 包） | 下载解压 |
| 本地 SKILL.md | 直接读 |
| 本地 zip 包 | 解压 |
安装步骤：
1. 找到 `SKILL.md`（可能在包的根目录或某个子目录里）
2. 从 frontmatter 里读出 `name`
3. 把**整个技能目录**（包括 `SKILL.md`、`scripts/`、`assets/` 等）复制到 `<workspace>/skills/<name>/`
4. 如果包里有 `INSTALL.md` 之类的安装脚本，照着跑一遍，但最终结果仍然要落在 `<workspace>/skills/<name>/` 下
## 从头创建技能
推荐按这个顺序来：
1. **搞清楚需求** — 让用户举几个具体的使用场景，一次别问太多
2. **想好结构** — 这个技能需要脚本吗？需要参考文档吗？需要模板素材吗？
3. **生成骨架** — 用初始化脚本：
```bash
scripts/init_skill.py <skill-name> --path <workspace>/skills [--resources scripts,references,assets] [--examples]
```
4. **填充内容** — 写好 SKILL.md、补上脚本和资源。脚本写完一定要实际跑一遍
5. **格式校验**（可选）：
```bash
scripts/quick_validate.py <workspace>/skills/<skill-name>
```
6. **迭代完善** — 实际用起来之后根据反馈持续改进
## 命名规则
- 只用小写字母、数字和中划线。用户给的名字需要做标准化处理，比如 `Plan Mode` → `plan-mode`
- 长度别超过 64 个字符
- 尽量短、用动词开头、一看就知道干什么
- 必要时用工具名做前缀，比如 `gh-address-comments`、`linear-address-issue`
- 目录名和 `name` 字段必须完全一致
## 三级加载机制
技能不会一次性全部塞进上下文，而是分三级按需加载：
1. **元信息**（`name` + `description`）— 常驻上下文，约 100 词。Agent 靠它判断「要不要用这个技能」
2. **SKILL.md 正文** — 确定要用了才加载，建议控制在 500 行以内
3. **资源文件** — Agent 需要的时候再读
如果一个技能涉及多个变体（比如多云厂商部署），建议这样组织：
```
cloud-deploy/
├── SKILL.md # 主流程和厂商选择逻辑
└── references/
├── aws.md
├── gcp.md
└── azure.md
```
用户选了 AWS，Agent 只需要读 `aws.md`，不用把三家的文档全加载进来。
## 常见设计模式
**步骤式**：按编号列出操作步骤和对应脚本。
```markdown
1. 分析表单结构（运行 analyze_form.py）
2. 生成字段映射（编辑 fields.json）
3. 自动填充表单（运行 fill_form.py）
```
**分支式**：根据用户意图走不同流程。
```markdown
1. 判断操作类型：
**新建内容？** → 走「创建流程」
**编辑已有内容？** → 走「编辑流程」
```
**模板式**：输出格式有严格要求时，在 SKILL.md 里直接给一个样板，让 Agent 照着写。

28
docs/zh/tools/bash.mdx Normal file
View File

@@ -0,0 +1,28 @@
---
title: bash - 终端
description: 执行系统命令
---
在当前工作目录执行 Bash 命令，返回 stdout 和 stderr。`env_config` 中配置的 API Key 会自动注入到环境变量中。
## 依赖
无额外依赖，默认可用。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `command` | string | 是 | 要执行的命令 |
| `timeout` | integer | 否 | 超时时间（秒） |
## 使用场景
- 安装软件包和依赖
- 运行代码和测试
- 部署应用和服务（Nginx 配置、进程管理等）
- 系统运维和排查
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260203121008.png" width="800" />
</Frame>

172
docs/zh/tools/browser.mdx Normal file
View File

@@ -0,0 +1,172 @@
---
title: browser - 浏览器
description: 控制浏览器访问和操作网页
---
控制 Chromium 浏览器进行网页导航、元素交互和内容提取。支持 JavaScript 渲染的动态页面，使用精简 DOM 快照让 Agent 高效理解页面结构。
## 安装
<Tabs>
<Tab title="CLI 安装（推荐）">
```bash
cow install-browser
```
该命令会自动完成：
- 安装 `playwright` Python 包（旧系统自动降级兼容版本）
- 在 Linux 上安装系统依赖
- 下载 Chromium 浏览器（Linux 服务器自动使用无头精简版）
- 自动检测国内网络并使用镜像加速
</Tab>
<Tab title="手动安装">
```bash
pip install playwright
playwright install chromium
```
Linux 服务器还需安装系统依赖：
```bash
sudo playwright install-deps chromium
```
如果系统较旧（如 Ubuntu 18.04，glibc < 2.28），需安装兼容版本：
```bash
pip install playwright==1.28.0
python -m playwright install chromium
```
国内网络下载 Chromium 较慢，可设置镜像加速：
```bash
export PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright
python -m playwright install chromium
```
</Tab>
</Tabs>
<Note>
1. 支持 Ubuntu 20.04+、Debian 10+、macOS、Windows。Ubuntu 18.04 等旧系统会自动降级安装兼容版本。
2. 浏览器工具依赖较重（约300MB），为可选安装。轻量的网页内容获取可使用 `web_fetch` 工具。
</Note>
## 工作流程
Agent 使用浏览器的典型流程：
1. **`navigate`** — 打开目标 URL
2. **`snapshot`** — 获取页面精简 DOM，交互元素自动编号（ref）
3. **`click` / `fill` / `select`** — 通过 ref 编号操作元素
4. **`snapshot`** — 再次快照验证操作结果
## 支持的操作
| 操作 | 说明 | 关键参数 |
| --- | --- | --- |
| `navigate` | 打开 URL | `url` |
| `snapshot` | 获取页面结构化文本（主要方式） | `selector`（可选） |
| `click` | 点击元素 | `ref` 或 `selector` |
| `fill` | 填入文本 | `ref` 或 `selector`，`text` |
| `select` | 下拉选择 | `ref` 或 `selector`，`value` |
| `scroll` | 滚动页面 | `direction`（up/down/left/right） |
| `screenshot` | 截图保存到工作区 | `full_page` |
| `wait` | 等待元素或超时 | `selector`，`timeout` |
| `press` | 按键（Enter、Tab 等） | `key` |
| `back` / `forward` | 浏览器前进/后退 | - |
| `get_text` | 获取元素文本内容 | `selector` |
| `evaluate` | 执行 JavaScript | `script` |
## 使用场景
- 访问指定 URL 获取动态页面内容
- 填写表单、登录操作
- 操作网页元素（点击按钮、选择选项等）
- 验证部署后的网页效果
- 抓取需要 JS 渲染的动态内容
## 运行模式
浏览器会根据运行环境自动选择模式：
| 环境 | 模式 |
| --- | --- |
| macOS / Windows | 有头模式（显示浏览器窗口） |
| Linux 桌面（有 DISPLAY） | 有头模式 |
| Linux 服务器（无 DISPLAY） | 无头模式（headless） |
可在 `config.json` 中手动覆盖：
```json
{
"tools": {
"browser": {
"headless": true
}
}
}
```
## 登录态持久化
**只需登录一次目标网站，Agent 后续可直接使用**。提供两种方式：
### 方式一：Persistent 模式（默认）
开箱即用，登录信息保存在 `~/.cow/browser_profile`。无需任何配置。
如需关闭持久化模式，每次都用纯净环境：
```json
{
"tools": {
"browser": {
"persistent": false
}
}
}
```
### 方式二：CDP 模式（接管真实 Chrome）
让 Agent 连接独立启动的真实 Chrome（而非 Playwright 自带的 Chromium），获得完整浏览器指纹，适合反爬严格的网站。
启动 Chrome 时加上调试端口和独立用户目录：
<Tabs>
<Tab title="macOS">
```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Linux">
```bash
google-chrome \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/.cow/chrome-cdp"
```
</Tab>
<Tab title="Windows">
```powershell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
--remote-debugging-port=9222 `
--user-data-dir="$env:USERPROFILE\.cow\chrome-cdp"
```
</Tab>
</Tabs>
在 `config.json` 中配置端点：
```json
{
"tools": {
"browser": {
"cdp_endpoint": "http://localhost:9222"
}
}
}
```
<Note>
Chrome 137+ 限制 `--remote-debugging-port` 必须搭配独立 `--user-data-dir`，因此 CDP 启动的 Chrome **无法直接复用你日常 Chrome 的登录态**，需要在独立目录中重新登录一次。
</Note>

24
docs/zh/tools/edit.mdx Normal file
View File

@@ -0,0 +1,24 @@
---
title: edit - 文件编辑
description: 通过精确文本替换编辑文件
---
通过精确文本替换编辑文件。如果 `oldText` 为空则追加到文件末尾。
## 依赖
无额外依赖，默认可用。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 是 | 文件路径 |
| `oldText` | string | 是 | 要替换的原始文本（为空时追加到末尾） |
| `newText` | string | 是 | 替换后的文本 |
## 使用场景
- 修改配置文件中的特定参数
- 修复代码中的 bug
- 在文件指定位置插入内容

36
docs/zh/tools/env-config.mdx Normal file
View File

@@ -0,0 +1,36 @@
---
title: env_config - 环境变量
description: 管理 API Key 等秘钥配置
---
管理工作空间 `.env` 文件中的环境变量（API Key 等秘钥），支持通过对话安全地添加和更新。内置安全保护和脱敏策略。
## 依赖
| 依赖 | 安装命令 |
| --- | --- |
| `python-dotenv` ≥ 1.0.0 | `pip install python-dotenv>=1.0.0` |
安装扩展依赖时已包含：`pip3 install -r requirements-optional.txt`
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `action` | string | 是 | 操作类型：`get`、`set`、`list`、`delete` |
| `key` | string | 否 | 环境变量名称 |
| `value` | string | 否 | 环境变量值（仅 `set` 时需要） |
## 使用方式
直接告诉 Agent 需要配置的秘钥，Agent 会自动调用该工具：
- "帮我配置 BOCHA_API_KEY"
- "设置 OPENAI_API_KEY 为 sk-xxx"
- "查看已配置的环境变量"
配置的秘钥会自动注入到 `bash` 工具的执行环境中。
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202234939.png" width="800" />
</Frame>

69
docs/zh/tools/index.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
title: 工具概览
description: CowAgent 内置工具系统
---
工具是 Agent 访问操作系统资源的核心能力。Agent 会根据任务需求智能选择和调用工具，完成文件操作、命令执行、联网搜索、定时任务等各类操作。工具实现在项目的 `agent/tools/` 目录下。
## 内置工具
以下工具默认可用，无需额外配置：
<CardGroup cols={2}>
<Card title="read - 文件读取" icon="file" href="/zh/tools/read">
读取文件内容，支持文本、图片、PDF
</Card>
<Card title="write - 文件写入" icon="pen" href="/zh/tools/write">
创建或覆盖写入文件
</Card>
<Card title="edit - 文件编辑" icon="pen-to-square" href="/zh/tools/edit">
通过精确文本替换编辑文件
</Card>
<Card title="ls - 目录列表" icon="folder-open" href="/zh/tools/ls">
列出目录内容
</Card>
<Card title="bash - 终端" icon="terminal" href="/zh/tools/bash">
执行系统命令
</Card>
<Card title="send - 文件发送" icon="paper-plane" href="/zh/tools/send">
向用户发送文件或图片
</Card>
<Card title="memory - 记忆" icon="brain" href="/zh/tools/memory">
搜索和读取长期记忆
</Card>
<Card title="env_config - 环境变量" icon="key" href="/zh/tools/env-config">
管理 API Key 等秘钥配置
</Card>
<Card title="web_fetch - 网页获取" icon="globe" href="/zh/tools/web-fetch">
获取网页或文档内容
</Card>
<Card title="scheduler - 定时任务" icon="clock" href="/zh/tools/scheduler">
创建和管理定时任务
</Card>
</CardGroup>
## 可选工具
以下工具需要安装额外依赖或配置 API Key 后启用：
<CardGroup cols={2}>
<Card title="web_search - 联网搜索" icon="magnifying-glass" href="/zh/tools/web-search">
搜索互联网获取实时信息
</Card>
<Card title="vision - 图片理解" icon="eye" href="/zh/tools/vision">
分析图片内容（识别、描述、OCR 文字提取等）
</Card>
<Card title="browser - 浏览器" icon="window" href="/zh/tools/browser">
控制浏览器访问和操作网页
</Card>
</CardGroup>
## MCP 工具
通过 [Model Context Protocol](https://modelcontextprotocol.io) 接入社区生态中的各种MCP工具，配置一次 `mcp.json` 即用即得：
<CardGroup cols={1}>
<Card title="MCP - 外部工具生态" icon="plug" href="/zh/tools/mcp">
支持 stdio / SSE 标准协议，热更新，零代码接入
</Card>
</CardGroup>

23
docs/zh/tools/ls.mdx Normal file
View File

@@ -0,0 +1,23 @@
---
title: ls - 目录列表
description: 列出目录内容
---
列出目录内容，按字母排序，目录名带 `/` 后缀，包含隐藏文件。
## 依赖
无额外依赖，默认可用。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 是 | 目录路径，相对路径基于工作空间目录 |
| `limit` | integer | 否 | 最大返回条目数，默认 500 |
## 使用场景
- 浏览项目结构
- 查找特定文件
- 检查目录是否存在

112
docs/zh/tools/mcp.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: MCP 工具
description: 通过 Model Context Protocol 接入外部工具生态
---
CowAgent 支持 [Model Context Protocol (MCP)](https://modelcontextprotocol.io)，让 Agent 能够直接调用社区中数以万计的 MCP 工具。配置一次 `mcp.json`，工具就会以与内置工具完全相同的方式呈现给 LLM，可被自动选择和调用。
## 配置文件
CowAgent 读取 `~/cow/mcp.json`。文件不存在时不会启用任何 MCP 工具，也不会报错。
Docker 部署时，官方 `docker-compose.yml` 已经把宿主机 `./cow` 挂载到容器内 `/home/agent/cow`（即容器用户的 `~/cow`），把 `mcp.json` 放进宿主机 `./cow/` 目录即可生效。
### 标准格式
完全兼容 MCP 社区标准，同 Claude Desktop / Cursor 一致：
```json
{
"mcpServers": {
"<server-name>": {
"command": "npx",
"args": ["-y", "some-mcp-package"],
"env": {
"API_KEY": "your-key-here"
}
}
}
}
```
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `command` | stdio | 启动 server 的可执行命令（如 `npx`、`python`、`uvx`） |
| `args` | 否 | 传给 command 的参数列表 |
| `env` | 否 | 子进程的环境变量，常用于 API Key |
| `url` | SSE / Streamable HTTP | 远程端点 URL（与 `command` 二选一） |
| `type` | 远程 | 远程传输类型，可选 `sse` 或 `streamable-http`，默认 `sse` |
| `headers` | 否 | 远程请求附加 HTTP 头（如 `Authorization`），仅 Streamable HTTP 使用 |
| `disabled` | 否 | `true` 时跳过该 server，便于临时关闭 |
### 完整示例
```json
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}
```
- **fetch**：通用网页抓取，返回页面文本内容，无需 API Key
- **github**：访问 GitHub 仓库、Issue、PR 等，需要 Personal Access Token
## 让 Agent 帮你配置
CowAgent 自带 `read` / `write` / `edit` 工具，**直接把要装的 MCP 配置发给 Agent，让它写到配置文件中：
例如：
```markdown
帮我把这个 MCP 加到 ~/cow/mcp.json 里：
{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}
```
Agent 会：
1. 访问 MCP 配置文件，合并新 server 配置，保留已有项
2. 自动重载增量的 MCP Server，下一次对话即可使用相应 Tools
## 工作方式
- 启动时**异步加载**：`mcp.json` 中配置的所有 server 会在后台异步加载，不阻塞主流程，对话可以立刻使用
- **热更新**：用户或 Agent 修改 `mcp.json` 后，消息处理完成时会自动重载变更的 server，无需重启 cow
- **平铺呈现**：每个 MCP server 暴露的多个方法会平铺为独立的工具，LLM 直接选择调用，不需要二次决策
## 支持的传输协议
| 协议 | 说明 | 配置字段 |
| --- | --- | --- |
| **stdio** | 子进程通信，最常见，社区生态最丰富 | `command` + `args` |
| **SSE** | HTTP Server-Sent Events，旧版远程协议 | `url`（默认） |
| **Streamable HTTP** | 新版远程协议，单端点收发，逐步取代 SSE | `type: "streamable-http"` + `url` |
## 排错
| 现象 | 排查方向 |
| --- | --- |
| 启动后 Agent 没有 MCP 工具 | 检查 `~/cow/mcp.json` 是否存在、JSON 格式是否合法 |
| 某个 server 加载失败 | 查看启动日志中的 `[MCP] Server 'xxx' load failed`，常见为依赖未装、API Key 缺失 |
| 修改 `mcp.json` 没有生效 | 改动会在**下一条消息**生效；若 server 配置不变（如只改注释），不会触发重启 |
| Docker 部署 | 确认宿主机 `./cow` 已挂载到容器内 `/home/agent/cow`，`mcp.json` 直接放进宿主机 `./cow/` 目录即可，或者直接对话 Agent 安装 |
## MCP 市场推荐
可以从各个第三方广场寻找现成的 MCP server，复制 JSON 配置即可使用，例如：
- [mcp.so](https://mcp.so) — 全球 MCP 服务索引
- [ModelScope MCP 广场](https://modelscope.cn/mcp) — 魔搭社区 MCP 广场，国内访问更稳定
只要遵循 MCP 标准协议（stdio / SSE / Streamable HTTP），都可以直接接入 CowAgent。

43
docs/zh/tools/memory.mdx Normal file
View File

@@ -0,0 +1,43 @@
---
title: memory - 记忆与知识
description: 搜索和读取长期记忆及知识库文件
---
记忆工具包含两个子工具：`memory_search`（搜索记忆）和 `memory_get`（读取记忆或知识文件）。
当 [知识库](/knowledge) 功能开启时，这两个工具同时支持访问 `memory/` 和 `knowledge/` 目录下的文件。
## 依赖
无额外依赖，默认可用。由 Agent Core 的记忆系统管理。
## memory_search
搜索历史记忆和知识库内容，支持关键词和向量混合检索。
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是 | 搜索查询 |
## memory_get
读取特定记忆文件或知识库文件的内容。
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 是 | 文件的相对路径（如 `MEMORY.md`、`memory/2026-01-01.md`、`knowledge/concepts/rag.md`） |
| `start_line` | integer | 否 | 起始行号 |
| `end_line` | integer | 否 | 结束行号 |
## 工作方式
Agent 会在以下场景自动调用记忆工具：
- 用户分享重要信息时 → 存储到记忆
- 需要参考历史信息时 → 搜索相关记忆
- 对话达到一定长度时 → 提取摘要存储
- 讨论到专业知识时 → 检索知识库中的相关页面
<Note>
当 `knowledge` 配置为 `false` 时，工具的描述和搜索范围会自动调整为仅包含记忆文件。
</Note>

24
docs/zh/tools/read.mdx Normal file
View File

@@ -0,0 +1,24 @@
---
title: read - 文件读取
description: 读取文件内容
---
读取文件内容。支持文本文件、PDF 文件、图片（返回元数据）等格式。
## 依赖
无额外依赖，默认可用。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 是 | 文件路径，相对路径基于工作空间目录 |
| `offset` | integer | 否 | 起始行号（1-indexed），负值表示从末尾读取 |
| `limit` | integer | 否 | 读取行数 |
## 使用场景
- 查看配置文件、日志文件
- 读取代码文件进行分析
- 检查图片/视频的文件信息

80
docs/zh/tools/scheduler.mdx Normal file
View File

@@ -0,0 +1,80 @@
---
title: scheduler - 定时任务
description: 创建和管理定时任务
---
创建和管理动态定时任务，支持灵活的调度方式和执行模式。
## 依赖
| 依赖 | 安装命令 |
| --- | --- |
| `croniter` ≥ 2.0.0 | `pip install croniter>=2.0.0` |
安装核心依赖时已包含：`pip3 install -r requirements.txt`
## 调度方式
| 方式 | 说明 |
| --- | --- |
| 一次性任务 | 在指定时间执行一次 |
| 固定间隔 | 按固定时间间隔重复执行 |
| Cron 表达式 | 使用 Cron 语法定义复杂调度规则 |
## 执行模式
- **固定消息发送**：到达触发时间时发送预设消息
- **Agent 动态任务**：到达触发时间时由 Agent 智能执行任务
## 使用方式
通过自然语言即可创建和管理定时任务：
- "每天早上 9 点给我发天气预报"
- "每隔 2 小时检查一下服务器状态"
- "明天下午 3 点提醒我开会"
- "查看所有定时任务"
<Frame>
<img src="https://cdn.link-ai.tech/doc/20260202195402.png" width="800" />
</Frame>
## 结果进入会话上下文
定时任务在隔离 session 中执行（内部规划与 tool 调用不污染用户会话），但**最终输出**会作为一对消息回写到接收者的真实会话，用户可以直接追问"刚才那条第二点展开说说"。
**默认策略**
- Agent 动态任务的输出进入上下文
- 固定消息类任务默认不进入上下文（可通过配置打开）
- 每个会话最多保留最近 **3 对** scheduler 消息，更早的自动清理；普通用户消息不受影响
**配置项**
| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `scheduler_inject_to_session` | `true` | 总开关 |
| `scheduler_inject_max_per_session` | `3` | 每会话保留 scheduler 消息对数上限 |
| `scheduler_inject_send_message` | `false` | 是否同时注入固定消息类任务 |
```json
{
"scheduler_inject_to_session": true,
"scheduler_inject_max_per_session": 3,
"scheduler_inject_send_message": false
}
```
## 任务执行时的上下文
定时任务的隔离 session 会保留最近几次执行的对话历史，便于做"对比上次"、"延续之前结论"等操作；但为了避免高频任务（如每 5 分钟监控）prompt 越积越长，会按公式自动裁剪：
```
scheduler_keep_turns = max(1, agent_max_context_turns / 5)
```
`agent_max_context_turns` 默认为 `20`，所以定时任务每次执行默认带最近 **4 轮**历史。需要更长记忆可调大 `agent_max_context_turns`。
<Note>
群聊场景（飞书 / 企微群机器人 / 钉钉等）下用户的真实 session_id 形如 `user_id:group_id`，与 receiver 不同。创建任务时会自动记录正确的 session_id；老的 `tasks.json` 缺该字段时回落到 receiver，行为与历史版本一致。
</Note>

23
docs/zh/tools/send.mdx Normal file
View File

@@ -0,0 +1,23 @@
---
title: send - 文件发送
description: 向用户发送文件
---
向用户发送文件（图片、视频、音频、文档等），当用户明确要求发送/分享文件时使用。
## 依赖
无额外依赖，默认可用。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 是 | 文件路径，可以是绝对路径或相对于工作空间的路径 |
| `message` | string | 否 | 附带的消息说明 |
## 使用场景
- 将生成的代码或文档发送给用户
- 发送截图、图表
- 分享下载的文件

75
docs/zh/tools/vision.mdx Normal file
View File

@@ -0,0 +1,75 @@
---
title: vision - 图片理解
description: 分析图片内容（识别、描述、OCR 等）
---
使用 Vision API 分析本地图片或图片 URL，支持内容描述、文字提取（OCR）、物体识别等。
## 模型选择
Vision 工具采用多级自动选择 + 自动兜底策略，无需手动配置即可使用：
1. **主模型** — 优先使用当前配置的主模型进行图像识别（需要是多模态模型）
2. **其他已配置模型** — 自动发现已配置 API Key 的其他多模态模型作为备选
如果当前 provider 调用失败，会自动尝试下一个，直到成功或全部失败。
### 支持的模型
| 厂商 | 视觉模型 | 说明 |
| --- | --- | --- |
| OpenAI / 兼容协议 | 使用主模型 | 支持所有 OpenAI 协议兼容的多模态模型 |
| 通义千问 (DashScope) | 使用主模型 | 例如 qwen3.6-plus 等 |
| Claude | 使用主模型 | Anthropic 原生图像格式 |
| Gemini | 使用主模型 | inlineData 格式 |
| 豆包 (Doubao) | 使用主模型 | doubao-seed-2-0 系列原生支持 |
| Kimi (Moonshot) | 使用主模型 | kimi-k2.6、kimi-k2.5 原生支持 |
| 百度千帆 (Qianfan) | 使用主模型 | 默认使用多模态主模型 (如 ernie-5.1)，主模型不支持时兜底使用 ernie-4.5-turbo-vl |
| 智谱 AI | glm-5v-turbo | 固定使用视觉专用模型 |
| MiniMax | MiniMax-Text-01 | 固定使用视觉专用模型 |
<Note>
智谱和 MiniMax 的文本模型不支持图像理解，因此始终使用对应的视觉专用模型，无需手动指定。
</Note>
> 当 `use_linkai=true` 时，默认使用 LinkAI 的多模态模型进行
## 自定义配置
如果希望指定 Vision 使用的模型，可在 `config.json` 中配置，例如：
```json
{
"tools": {
"vision": {
"model": "gpt-4.1"
}
}
}
```
指定的模型会被**优先使用**，工具会根据模型名自动路由到对应的 provider；若调用失败，会自动 fallback 到其他已配置的 provider。
大多数情况下无需配置，主模型支持多模态或配置任意一个支持视觉的 API Key 即可自动工作。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `image` | string | 是 | 本地文件路径或 HTTP(S) 图片 URL |
| `question` | string | 是 | 对图片提出的问题 |
支持的图片格式：jpg、jpeg、png、gif、webp
## 使用场景
- 描述图片中的内容
- 提取图片中的文字（OCR）
- 识别物体、颜色、场景
- 分析截图、文档扫描图片等
<Note>
超过 1MB 的图片会自动压缩后上传，所有图片（包括远程 URL）会统一转为 base64 传输，确保兼容所有模型后端。
</Note>

32
docs/zh/tools/web-fetch.mdx Normal file
View File

@@ -0,0 +1,32 @@
---
title: web_fetch - 网页获取
description: 获取网页或文档内容
---
获取 HTTP/HTTPS URL 的内容。对网页提取可读文本，对文档文件（PDF、Word、Excel 等）自动下载并解析内容。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | HTTP/HTTPS URL（网页或文档链接） |
## 支持的文件类型
| 类型 | 格式 |
| --- | --- |
| PDF | `.pdf` |
| Word | `.docx` |
| 文本 | `.txt`、`.md`、`.csv`、`.log` |
| 表格 | `.xls`、`.xlsx` |
| 演示文稿 | `.ppt`、`.pptx` |
## 使用场景
- 获取网页的文本内容
- 下载并解析远程文档
- 获取 API 响应内容
<Note>
`web_fetch` 只能获取静态 HTML 内容。如果页面需要 JavaScript 渲染（如 SPA 单页应用），请使用 `browser` 工具。
</Note>

51
docs/zh/tools/web-search.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
title: web_search - 联网搜索
description: 搜索互联网获取实时信息，支持多个搜索厂商
---
搜索互联网获取实时信息、新闻、研究等内容。支持博查、百度千帆、智谱、LinkAI 四个后端，配置任意一家即可使用。
<Tip>
推荐通过 [Web 控制台](/zh/channels/web) 的「模型管理 → 搜索」面板可视化配置厂商与策略，无需手动编辑配置文件。
</Tip>
## 厂商
| 厂商 | 凭证 | 申请入口 |
| --- | --- | --- |
| 博查 Bocha | `tools.web_search.bocha_api_key` | [博查开放平台](https://open.bochaai.com/) |
| 百度千帆 | 复用 `qianfan_api_key` | [千帆控制台](https://cloud.baidu.com/doc/qianfan/s/2mh4su4uy) |
| 智谱 Zhipu | 复用 `zhipu_ai_api_key` | [智谱开放平台](https://docs.bigmodel.cn/cn/guide/tools/web-search) |
| LinkAI | 复用 `linkai_api_key` | [LinkAI 控制台](https://link-ai.tech/console/interface) |
除博查需要单独的 `bocha_api_key` 外，其他三家直接复用对应模型的 API Key，配好模型即同时获得搜索能力。
## 路由策略
```json
{
"tools": {
"web_search": {
"strategy": "auto",
"provider": ""
}
}
}
```
- `auto`（默认）：由 Agent 在已配置的厂商中智能选择，并可在一次任务中多次调用、切换不同厂商以获取更全面的结果；未指定时按 `bocha → qianfan → zhipu → linkai` 顺序兜底。
- `fixed`：固定使用 `provider` 指定的厂商；该厂商凭证缺失时自动回落到 auto 顺序。
## 工具参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是 | 搜索关键词 |
| `count` | integer | 否 | 返回结果数量（1–50，默认 10） |
| `freshness` | string | 否 | 时间范围：`noLimit`（默认）、`oneDay`、`oneWeek`、`oneMonth`、`oneYear`，或日期范围如 `2025-01-01..2025-02-01` |
| `summary` | boolean | 否 | 是否返回页面摘要（默认 false） |
| `provider` | string | 否 | `auto` 策略下配置了多个厂商时可见，用于单次切换厂商 |
<Note>
四家凭证均未配置时，该工具不会注册到 Agent。
</Note>

27
docs/zh/tools/write.mdx Normal file
View File

@@ -0,0 +1,27 @@
---
title: write - 文件写入
description: 创建或覆盖写入文件
---
写入内容到文件。文件不存在则自动创建，已存在则覆盖。自动创建父目录。
## 依赖
无额外依赖，默认可用。
## 参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 是 | 文件路径 |
| `content` | string | 是 | 要写入的内容 |
## 使用场景
- 创建新的代码文件或脚本
- 生成配置文件
- 保存处理结果
<Note>
单次写入不应超过 10KB。对于大文件，建议先创建骨架，再使用 edit 工具分块添加内容。
</Note>