> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# v2.2.1

> CowAgent 2.2.1：新增产物中心与自定义菜单，开放 Agent 对话 API，模型缓存与上下文成本优化，工具、通道与安全性完善

🌐 [English](https://docs.cowagent.ai/releases/v2.2.1) | [中文](https://docs.cowagent.ai/zh/releases/v2.2.1)

## 📁 产物中心

新增「产物」页面，集中管理对话中生成的文件，Web 控制台与桌面客户端均已支持：

* **自动收录**：Agent 写入的文件、命令生成的文件、子 Agent 汇报的文件及发送给用户的文档，均自动收录并跨 Agent 按时间线展示。
* **预览与回溯**：支持按类型、Agent 筛选和搜索，可直接预览，并跳转回生成该文件的对话（Thanks @rudycelekli #3732）。
* **整理**：支持置顶、重命名、移除；对话中的文件卡片可直接定位到产物中心。产物页面默认隐藏，可在菜单编辑中开启。
* **问题修复**：修复旧版数据库升级、Windows 路径及历史消息定位问题（Thanks @Lesereingrape #3450, #3514、@aniruddhaadak80 #3402）。

## 🧭 自定义菜单与控制台

* **自定义菜单**：Web 控制台与桌面客户端支持自定义菜单的分组、顺序、名称、图标与显示状态，两端配置共享；产物文件与网页链接可添加为菜单项。详见 [自定义菜单](https://docs.cowagent.ai/zh/extensions/custom-menu)。
* **侧边栏折叠**：Web 控制台侧边栏可折叠为图标栏。
* **知识库编辑与技能编写**：控制台可直接编辑知识库页面并自动更新索引，支持从零编写技能及编辑技能目录下的文件。Thanks @zkjqd (#3377)
* **Token 用量**：每条回复展示本轮实际消耗的 Token 及缓存命中情况。Thanks @Harbor404 (#3440)
* **Mermaid 图表**：Mermaid 代码块可切换为图表预览，支持缩放与全屏。Thanks @akushonkamen (#3620)
* **Agent ID**：智能体页面展示 Agent ID 并支持一键复制。
* **长会话加载**：工具调用较多的会话打开速度更快。
* **问题修复**：新会话标题不再丢失，默认 Agent 的会话管理操作不再报错（Thanks @6vision #3625, #3617）；配置项一并生效，工作空间文件按所属 Agent 保存（Thanks @aniruddhaadak80 #3454, #3488）。

## 🔌 开放 Agent 对话 API

Web 控制台端口提供标准对话接口，可接入第三方客户端，或在业务系统中直接调用 Agent：

* **开关与密钥**：在「配置」页一键开启并生成 API Key，关闭后 Key 保留；也支持通过配置文件或环境变量开启（Thanks @Bdysj #3342）。
* **指定 Agent 与模型**：通过 `agent_id` 指定 Agent，通过 `model` 指定模型，未指定时使用 Agent 的默认模型。
* **多轮会话**：默认由调用方传入完整消息历史；传入 `conversation_id` 后由服务端保存历史，只需发送最新消息。
* **完整输出**：支持流式与非流式响应，返回思考内容、Token 用量及工具调用过程（Thanks @c020627 #3545, #3588）。

相关文档：[对话 API](https://docs.cowagent.ai/zh/extensions/chat-api)

## 📐 模型缓存与上下文成本优化

* **Claude 提示词缓存**：缓存系统提示词、工具定义与对话前缀，显著提升缓存命中率，降低 Token 成本与响应延迟；缓存时长可通过 `claude_cache_ttl` 配置。
* **裁剪预留空间**：上下文裁剪后预留空间，后续若干轮不再改动前缀，长会话也能持续命中缓存。
* **预算即时生效**：修改上下文预算与最大步数后直接作用于运行中的 Agent，不再清空会话。
* **压缩保留工具记录**：压缩后的历史轮次保留工具调用摘要，避免模型编造执行结果（Thanks @tsumon #3634）。
* **问题修复**：压缩期间到达的消息不再丢失，孤立工具结果的清理更准确（Thanks @c020627 #3518、@rudycelekli #3652, #3653）。

## 🤖 模型能力

* **Claude 长思考**：长时间思考时保持连接不中断，输出停滞时自动降低思考强度重试。
* **自定义请求头**：自定义模型厂商支持配置 `headers`，并适配 OpenCode Go。
* **模型自动发现**：编辑模型列表时可自动拉取厂商的可用模型。Thanks @Harbor404 (#3441)
* **思考内容**：兼容 `reasoning`、`thinking` 字段，未闭合的 `<think>` 标签不再截断回复（Thanks @a1094174619 #3601、@fly0sheep-1734 #3538）。
* **备用模型**：备用模型在每轮对话开始时重置，不再持续占用。
* **OpenAI**：完善 Responses 接口与流式响应处理（Thanks @rudycelekli #3659, #3660, #3661, #3663、@aniruddhaadak80 #3486）。
* **模型列表**：修复并发编辑覆盖、自定义主模型不生效、能力标签匹配等问题（Thanks @rudycelekli #3577, #3662, #3666、@aniruddhaadak80 #3501）。
* **其他厂商**：修复 MiniMax、ModelScope、百度文心、Azure DALL·E 的兼容问题（Thanks @aniruddhaadak80 #3464, #3476, #3479, #3507, #3512、@rudycelekli #3678）。
* **错误处理**：被拒绝的请求不再重复发送，错误信息识别更准确，上下文用量显示真实 Token 数（Thanks @c020627 #3442, #3443, #3445、@aniruddhaadak80 #3505、@6vision #3624）。
* **图像**：图像生成保留原格式与原始提示词，macOS 下视觉识别不再放大图片（Thanks @aniruddhaadak80 #3503, #3504、@rudycelekli #3568）。

## 🧠 记忆与知识库

* **命中反馈排序**：新增可选的 `memory.hit_boost`，经常被检索到的记忆排序略微靠前，默认关闭。Thanks @foreverjix (#3621)
* **时间衰减**：仅对每日记忆文件生效，带日期的知识库页面不再被降权（Thanks @fly0sheep-1734 #3376）。
* **索引**：修复超长行内容丢失、分块超出预算、清空笔记后索引残留等问题（Thanks @fly0sheep-1734 #3585、@rudycelekli #3426, #3578, #3616）。
* **检索**：优化全文检索回退、Unicode 关键词、参数与向量异常处理（Thanks @aniruddhaadak80 #3480, #3481, #3482, #3483、@rudycelekli #3559, #3656, #3658）。
* **记忆写入**：写入失败后可重试，兼容导入旧版会话数据（Thanks @aniruddhaadak80 #3406、@c020627 #3590、@rudycelekli #3387）。
* **知识库**：修复 Windows 下图谱路径、大写扩展名文档不显示等问题，加强导入路径校验（Thanks @Lesereingrape #3332、@rudycelekli #3612, #3649, #3651）。

## 🤝 多 Agent 协作

* **权限与委派**：委派和交接时沿用发起方的权限模式，接收方重新校验委派白名单、深度与等待时间（Thanks @c020627 #3541, #3546, #3547, #3548, #3552）。
* **默认 Agent 别名**：统一解析为默认 Agent 的真实 ID（Thanks @c020627 #3553, #3554）。
* **团队会话**：删除团队会话时同步清理所有参与者的记录，修复模型设置显示与追加消息投递问题（Thanks @c020627 #3519, #3537, #3549, #3550, #3613）。
* **子 Agent**：停止任务时同步停止子 Agent，修复提示词解析问题（Thanks @rudycelekli #3637, #3638, #3639）。
* **会话与项目**：修复会话设置与项目路径的异常处理（Thanks @c020627 #3551、@rudycelekli #3640, #3654）。

## 🧩 工具与技能

* **文件读写**：写入失败时保留原文件，修复换行符识别、并发编辑覆盖、参数解析等问题（Thanks @aniruddhaadak80 #3365, #3404, #3413、@rudycelekli #3525, #3531, #3563, #3566, #3567, #3667）。
* **文档解析**：完整保留 Word 表格、Excel 公式与 PowerPoint 表格内容（Thanks @rudycelekli #3393, #3394, #3560, #3629, #3631）。
* **文件搜索**：外部搜索失败时自动回退，修复过滤规则、大小写与特殊文件处理（Thanks @aniruddhaadak80 #3400、@rudycelekli #3391, #3533, #3534, #3558, #3570, #3571, #3630, #3675, #3679）。
* **网页抓取**：正确识别字符集与文档类型，限制传输时间与大小（Thanks @aniruddhaadak80 #3401, #3478、@rudycelekli #3392, #3569, #3574, #3632, #3669, #3670, #3671）。
* **浏览器**：页面跟随窗口尺寸显示（Thanks @zkjqd #3623）；Docker 中正确识别内置 Chromium，安装无需 `sudo`（Thanks @handoing #3743, #3744）；修复启动失败回收、滚动与元素操作问题（Thanks @c020627 #3524、@aniruddhaadak80 #3490、@rudycelekli #3562, #3573）。
* **终端**：修复多字节字符截断、退出码误报与 `.env` 解析问题（Thanks @rudycelekli #3530, #3564, #3668）。
* **MCP**：Windows 下正确启动 `npx`、`uvx` 等命令（Thanks @6vision #3408）；支持分页获取工具、结构化结果与错误透传（Thanks @rudycelekli #3672, #3673, #3674、@aniruddhaadak80 #3425）；连接超时与配置保存更可靠（Thanks @aniruddhaadak80 #3414, #3452, #3466, #3469、@c020627 #3438, #3523, #3542, #3610, #3615）。
* **技能**：兼容更多 GitHub 目录结构，修复安装路径、目录循环与 YAML 解析问题（Thanks @aniruddhaadak80 #3379、@rudycelekli #3389, #3594, #3597, #3598、@c020627 #3516, #3682）。
* **定时任务**：拒绝创建已过期的一次性任务，修复夏令时、任务类型校验、任务文件恢复与投递对象等问题，兼容 Python 3.9 以下版本（Thanks @aniruddhaadak80 #3359, #3374, #3375, #3429、@c020627 #3540, #3604, #3683、@rudycelekli #3390, #3526, #3532, #3575, #3576, #3593, #3636）。

## 📡 通道能力

* **微信**：登录状态更稳定，删除实例时清理凭证，修复同名附件覆盖与临时文件残留（Thanks @c020627 #3277, #3544, #3581, #3589, #3622、@6vision #3609、@aniruddhaadak80 #3498、@rudycelekli #3635）。
* **企业微信**：令牌刷新失败后自动恢复，修复智能机器人回复流、图片转换与重复回调问题，及时清理临时文件（Thanks @c020627 #3345, #3435, #3529, #3611, #3614、@aniruddhaadak80 #3397, #3497、@rudycelekli #3645）。
* **微信客服**：消息游标写入失败时自动重试（Thanks @rudycelekli #3677）。
* **微信公众号**：修复视频回复丢失、被动回复后用户无响应等问题（Thanks @aniruddhaadak80 #3360, #3411、@c020627 #3536, #3543, #3606）。
* **飞书**：代码中的 Markdown 图片语法原样保留（Thanks @huiq777 #3434）；修复令牌请求超时与应用重新注册问题（Thanks @aniruddhaadak80 #3358、@c020627 #3539）。
* **钉钉**：卡片回复中的代码块原样保留（Thanks @huiq777 #3420）；修复发送结果判断与图片说明重复发送（Thanks @aniruddhaadak80 #3396, #3496、@c020627 #3432, #3517, #3586）。
* **QQ**：支持发送超过 5MB 的文件（Thanks @HnBigVolibear #3647）；支持图片回复，修复断线重连问题（Thanks @c020627 #3341、@aniruddhaadak80 #3405）。
* **Telegram**：修复带格式消息处理中断与链接渲染问题（Thanks @fly0sheep-1734 #3522、@rudycelekli #3665、@aniruddhaadak80 #3416）。
* **Slack / Discord**：发送失败时自动重试（Thanks @aniruddhaadak80 #3415）。
* **通用**：
  * 过期附件不再随下一条消息发送（Thanks @SEVEN-us #3407）；修复附件并发、缓存清理与扩展名问题（Thanks @c020627 #3437、@rudycelekli #3561, #3644）。
  * 去重缓存定期清理，长期运行不再持续占用内存（Thanks @Bdysj #3340）。
  * 修复消息处理中断、取消死锁、通道停止与凭证覆盖等问题（Thanks @c020627 #3348, #3515、@aniruddhaadak80 #3373, #3395, #3410、@rudycelekli #3384, #3648, #3655）。

## 🛡 安全加固

* **权限控制**：只读模式拦截遗漏的 git 写操作（Thanks @aniruddhaadak80 #3352、@drakeo338 #3357）；识别命令替换、参数写入与根目录删除等危险操作（Thanks @c020627 #3579, #3602、@aniruddhaadak80 #3506）；非完全访问模式下禁止修改 MCP 配置与会话权限。
* **路径访问**：加强上传、静态资源、技能卸载、备份恢复等场景的路径校验，拦截凭证类文件（Thanks @aniruddhaadak80 #3409, #3460, #3461, #3463、@c020627 #3446、@rudycelekli #3527, #3528、@Harbor404 #3436）。
* **外部资源**：统一限制下载大小，校验媒体地址与证书（Thanks @c020627 #3327, #3328, #3329, #3336, #3555, #3556, #3557、@rudycelekli #3428、@aniruddhaadak80 #3457, #3477）。
* **日志脱敏**：访问令牌与密钥不再明文写入日志（Thanks @c020627 #3356, #3444、@aniruddhaadak80 #3369, #3399, #3511）。
* **配置健壮性**：`.env` 拒绝含换行的值（Thanks @Lesereingrape #3344）；兼容带 BOM 的配置文件，加强配置类型校验与原子写入（Thanks @c020627 #3412, #3433, #3447, #3448、@aniruddhaadak80 #3431, #3499、@rudycelekli #3641）。

## 🛠 其他优化与修复

* **Agent 执行**：修复工具异常、步数上限覆盖回答、取消与并发等问题（Thanks @aniruddhaadak80 #3383, #3403, #3424、@c020627 #3582, #3583, #3587、@rudycelekli #3388, #3643, #3650）。
* **语音**：文字转语音失败时仍发送文本回复，修复多个语音服务的超时与错误处理（Thanks @c020627 #3684、@aniruddhaadak80 #3330, #3363, #3491）。
* **插件**：修复插件重载、重复注册、空消息、关键词与角色插件等问题（Thanks @aniruddhaadak80 #3367, #3398、@c020627 #3520, #3521, #3584、@rudycelekli #3664, #3728）。
* **自我进化**：快照恢复与备份更可靠（Thanks @rudycelekli #3385, #3657、@c020627 #3600）。
* **Agent 管理**：删除 Agent 时同步清理头像与会话（Thanks @c020627 #3580, #3603）。
* **CLI 与备份**：`/status` 显示已加载的 MCP 服务（Thanks @HnBigVolibear #3474）；修复备份、配置读取、知识库列表与 Git worktree 更新问题（Thanks @rudycelekli #3592, #3595, #3596, #3599, #3607）。
* **日志**：日志页面读取更稳定，实时日志不再丢行（Thanks @c020627 #3349、@rudycelekli #3642）。
* **简繁转换**：修正简繁对照表（Thanks @aniruddhaadak80 #3347）。
* **Docker**：Compose 模板默认启用 Web 控制台，首次启动后可在控制台配置模型。
* **桌面客户端**：重装后恢复快捷方式，自定义更新源时保留更新渠道。
* **文档**：
  * 补充 Docker 升级的数据目录说明（Thanks @Frank-zhu2000 #3680）
  * 修复日文模型页面链接（Thanks @pratikgx #3681）
  * MCP 文档与控制台用语保持一致（Thanks @c020627 #3418）

## 📦 升级方式

* **源码部署**：执行 `cow update` 一键升级，或在 Web 控制台侧边栏版本菜单中一键更新，也可手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/zh/guide/upgrade)。
* **桌面客户端**：可在客户端内自动检查并一键更新，或前往 [下载页](https://cowagent.ai/zh/download/) 获取最新版本。

**发布日期**：2026.10.14 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.2.0...2.2.1)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.