CowAgent 框架全解：从一条消息的旅程，看懂 chatgpt-on-wechat 的架构设计
CowAgent 框架全解：从一条消息的旅程，看懂 chatgpt-on-wechat 的架构设计
基于 v2.2.1 源码实读（非官方文档转述）。项目原名 chatgpt-on-wechat，现已更名为 CowAgent，定位也从「微信接入 ChatGPT」演进为一套完整的 Agent Harness 参考实现。一、一句话定位
CowAgent 是一个开源超级 AI 助手框架：消息从十余种渠道进来，由 Agent 内核规划、推理、调用工具与技能，再把结果发回原渠道，可以 7×24 跑在个人电脑或服务器上，接入任意主流大模型。
它的工程价值在于：把「大模型 API + IM 渠道」这个看似简单的组合，做成了层与层彻底解耦、每层可独立扩展的框架。
二、整体分层架构
整个工程只有五层，层与层之间只靠 Context（入）和 Reply（出）两个对象传递，没有横向 import：
渠道层 channel/：12+ 渠道。Web 控制台（默认端口 9899）是默认渠道；其余覆盖微信、企业微信、飞书、钉钉、QQ、Telegram、Slack、Discord、公众号、微信客服，外加 Electron 桌面端。
桥接层 bridge/：
Bridge是单例门面，同时保留旧 bot / voice / translate 工厂；AgentBridge负责 create_agent / agent_reply，AgentInitializer负责组装运行时。Agent 运行时 agent/protocol/：Agent 容器（system prompt + 工具表）、
AgentStreamExecutor（tool-call 主循环）、cancel / steer 注册表。能力层：工具 agent/tools/、技能 agent/skills/、模型 models/。
状态层：
common/state_dir定义的 ~/cow 工作区契约、SQLite 会话历史、agent/memory 三层记忆。
这个设计解释了为什么 12 渠道 × 18 模型能自由组合——因为任何一层都不知道其他层的存在。
三、一条消息的完整旅程
消息进入
ChatChannel子类，先做语音转文本、媒体下载缓存，插件可在此前置拦截（godcmd 管理指令、keyword 关键词等）。_compose_context判定私聊/群聊、群白名单、@检查，组装成 Context。produce丢进会话队列——同一 session 严格串行，避免并发回复错乱。Bridge 取出该 session 的持久会话历史，调用
agent_reply进入 Agent 运行时。run_stream主循环里 LLM 与工具交替执行（下节展开）。过程中以流式事件（delta / thinking / 工具卡片）回推渠道；结束后会话落库、记忆摘要入队。
_decorate_reply做装饰（Markdown 围栏、@ 前缀、长文分片），_send_reply发回用户。
运行中用户随时可以 /cancel 打断、/steer 追加指令——靠 contextvars 穿透线程的注册表实现，不用等到本轮结束。
四、Agent 内核：tool-call 主循环
agent/protocol/agent_stream.py 的 run_stream 是整个框架的「心脏」：
进循环前一次性裁剪上下文，裁剪点保证不留孤儿 tool_use（否则 API 直接报错）。
每轮先检查 cancel 注册表（轮间到达的打断在此短路），再把 steer 指令并入本轮消息。
finish_reason为 tool_calls 时解析参数——json_repair修复畸形 JSON，length 截断则提示模型重发；多工具且parallel_safe时用线程池并行执行。循环外还有三个韧性机制：模型 fallback 链（主模型耗尽重试后按链切换，且是粘性的，本轮不再弹回）、工具熔断（同名同参连续失败即熔断，防死循环烧 token）、thinking 流剥离（跨 chunk 半截标签有缓冲）。
轮数上限默认 30（
agent_max_turns）。
五、记忆：三层架构 + Deep Dream
记忆是 CowAgent 最有辨识度的设计：
短期层：当前上下文。超预算时按「完整轮」裁剪，被丢弃的内容压缩成摘要回填，绝不留下断链。
中期层：daily 文件。
MemoryFlushManager每日定时把被丢弃消息用 LLM 摘要成「当日记录」，追写memory/YYYY-MM-DD.md。长期层：MEMORY.md。夜间 Deep Dream 把现有长期条目 + 当日日记蒸馏精炼，回写长期层，另产出一份「梦境日记」。MEMORY.md 每次对话都注入 system prompt，所以必须保持精炼。
检索：关键词 FTS + 向量混合，未配 embedding 时自动降级纯关键词。
三层写入全部自动发生，用户不需要「保存记忆」这个动作。
六、能力层：工具、技能与模型
工具（原子能力）
文件读写（read / write / edit / ls）、终端 bash、浏览器自动化、调度器、记忆检索、web 搜索、视觉等十余个内置工具；通过 MCP 协议（一份 mcp.json，支持 stdio / SSE、热重载）接入整个开放生态。
技能（工作流）
SKILL.md + scripts/ + resources/ 构成一个技能目录，可从 Skill Hub 市场、GitHub、ClawHub、URL 一键安装，也能在对话里用 skill-creator 让 Agent 自己生成。加载时校验 frontmatter（name / description / emoji / requires），requires 不满足则不注入；自定义技能优先级高于内置，同名覆盖。
模型（provider 工厂）
DeepSeek、Claude、OpenAI、Gemini、MiniMax、GLM、Qwen、Kimi、Doubao、文心、MiMo、LinkAI 及自定义兼容接口。Chat / 视觉 / 画图 / ASR / TTS / Embedding 可分别路由到不同厂商，全部在 Web 控制台里切换，不改配置文件。
七、多 Agent 与自进化
多 Agent：
AgentRouter + AgentRegistry管理团队花名册（agents/team.json）。正式队友有独立 workspace 和独立记忆，可在共享会话里被 @ 编排；sub-agent 则是临时执行单元，共享主 Agent 工作区、无独立记忆，用于并行派生。自进化：后台线程每 60s 扫描活跃会话，空闲 ≥10 分钟且（距上次进化 ≥6 个用户轮 或 上下文超预算 80%）时触发。进化在隔离环境跑一次复盘 Agent：改进已有技能、跟进未完成任务、回填记忆与知识，全程由 backup.py 备份、可回滚。
八、权限与安全
会话级三种权限模式：
| 模式 | 行为 |
|---|---|
| read-only | 拒绝所有写 + bash 只允许白名单只读命令 + 有副作用工具全拒 |
| workspace-write | 工作目录内自由写；越界写拒；放权文件（MCP 配置 / config / 凭据 / 会话设置）拒 |
| full-access | 不设限（历史默认） |
bash 命令会解析重定向、rm / mv 越界、提权（尽力而为，非 OS 沙箱）。拒绝时返回 permission_denied 标记，前端提示用户切换权限而非笼统报错。
九、状态目录契约（~/cow）
所有状态收敛到 ~/cow 一个目录，分三类：
系统共享：skills / knowledge / mcp、
~/.cow/.env密钥、agents/team.json 团队花名册。每 Agent 隔离：SYSTEM.md / USER.md / AGENT.md / RULE.md、MEMORY.md + memory/、sessions/、tmp/。
每终端用户：画像 / 偏好 / 记忆 / 任务记录。
设计规则：共享的复制会漂移 → 谁用谁建；每 Agent 的 = 「之所以是不同 Agent」；每用户的 = 关于人而非 Agent 的事实。
十、配置、启动与部署
配置：
config.json（模板 config-template.json），启动后大部分可在 Web 控制台改。启动：一行安装脚本（Linux/macOS bash、Windows PowerShell、docker compose 三选一），默认
http://localhost:9899开 Web 控制台。CLI：
cow start | stop | restart | status | logs | update | skill install。桌面端：macOS / Windows 客户端，内置后端开箱即用。
本机交付：仓库根目录的
cow-start.cmd / cow-stop.cmd做了就绪轮询、端口占用检测、日志尾部打印，双击即用。
十一、插件系统
plugins/ 下是经典插件机制（Event + Plugin 基类，plugin_manager 统一调度），内置 godcmd（管理员）、keyword、role、dungeon、banwords、finish、hello、tool、linkai 等。插件在渠道层前置/后置拦截，与 Agent 层正交——这是从 bot 时代继承下来的扩展面，与 skills 体系并行不悖。
十二、结语
CowAgent 的框架价值可以压缩成三句话：
渠道与模型彻底解耦，所以 12 渠道 × 18 模型能自由组合；
Agent 内核只认 tool-call 循环，所以任何能力（工具、技能、MCP、多 Agent）都能长进去；
状态全部收敛到 ~/cow，所以整个助手可以像目录一样备份和迁移。
延伸阅读：同目录的《CowAgent-技术图解》有 13 张源码级时序 / 流程图，每个环节都标注了对应源码位置，适合对照阅读。
