cheetahclaws · 智能体框架与编排

从 28 万行 TypeScript 到 9 万行 Python：一场重新发明 Claude Code 的实验

Claude Code 是 Anthropic 官方推出的 AI 编程助手，功能强大，但它的源代码是一个约 12 MB 的编译后 TypeScript/Node Bundle（超 1300 个文件，约 28.3 万行代码），与 Anthropic API 深度耦合，修改门槛极高，且无法对接本地模型或其他云端供应商。

CheetahClaws 正是对这个问题的一次正面回应——它在约 9 万行可读的 Python 代码中重新实现了 Claude Code 的核心循环，保留了真正重要的部分，删除了不必要的部分，并叠加了多供应商 + 本地模型支持。2026 年 6 月 16 日项目刚刚完成 v3.5.82 版本的大规模重构，将所有内部模块统一收束到 cheetahclaws 包命名空间下，解决了与其他项目 config/ 目录或 PyPI python-daemon 包冲突导致的 ImportError 问题，测试覆盖率达 2449 个用例全部通过。

CheetahClaws Web UI 截图

图1：CheetahClaws Web UI 截图，支持多用户浏览器对话、工具卡片和 Markdown 流式输出

什么是 Agent Harness（智能体线束）？

"Agent Harness" 这个概念对普通用户可能陌生，但类比非常直观——就像给赛车换装一套通用接口的线束，让同一套电子设备可以无缝适配不同发动机。CheetahClaws 本质上是一套让 AI 智能体（Agent）能够自主循环执行任务的运行时基础设施：接收用户指令 → 调用工具 → 观察结果 → 继续决策 → 直到任务完成。

传统的 Claude Code 是一个封闭的黑盒：模型固定（Claude）、工具固定、行为固定。而 CheetahClaws 做了三件关键的事：

第一，多模型支持。 支持 Anthropic、OpenAI、Google Gemini、Moonshot(Kimi)、阿里 Qwen、智谱 GLM、DeepSeek、MiniMax 等 8+ 云端供应商，以及通过 Ollama / LM Studio / vLLM 对接任意本地模型。切换模型只需一条命令 --model ollama/qwen2.5-coder，无需重新编译。

第二，可读的 Agent 循环。 整个 Agent 主循环（streaming + tool-use）集中在单个 agent.py 文件中，约 740 行，代码结构清晰可审计。相比 Claude Code 28 万行的编译产物，CheetahClaws 让研究者和开发者能真正理解"AI Agent 内部是如何运转的"。

第三，开放扩展机制。 支持 MCP（Model Context Protocol）服务器接入（stdio/SSE/HTTP 三种协议）、Markdown 格式的 Skill 技能系统、Git 插件系统、运行时动态工具注册（register_tool()），以及 bridges（桥接器）将 AI 能力输出到 Telegram、微信、Slack、QQ 等即时通讯平台。

核心架构：从 Kernel 到 Daemon 的分层设计

CheetahClaws 的代码结构可以大致分为五层，每一层都有明确的职责边界。

第一层：Provider（供应商抽象）。 providers.py 实现了统一的 Provider 接口，将 Anthropic 的 SDK 调用、OpenAI 的 SDK 调用、以及 Ollama 的原始 HTTP 请求全部转换为内部统一的 AssistantTurn（助手轮次）和 TextChunk/ThinkingChunk（文本/思考块）格式。无论底层用的是哪个模型，Agent 核心看到的永远是同一种数据结构。

第二层：Agent Core（Agent 核心循环）。 agent.py 实现了生成器风格（Generator-based）的多轮对话循环，核心逻辑约 740 行。它负责管理消息历史（messages）、Token 计数、上下文窗口压缩（compaction）、循环检测（loop guard）——防止模型在工具调用失败时陷入无限重试，以及只读去重（Read/Glob/Grep 等工具的重复调用结果直接复用而非真正执行）。

第三层：Kernel（内核子系统）。 这是最复杂的子系统，包含以下子模块：

Capability Store（能力存储）：基于 RFC 0005 的权限模型，每个 Agent 进程（pid）持有自己的工具权限集（tool grants），与 Linux 的 capability 模型一脉相承。
Ledger（分类账）：RFC 0006 实现，对每个 Agent 的 Token 消费、配额使用进行精确记账。
Scheduler（调度器）：RFC 0007，实现 Agent 的时间片调度、阻塞等待（blocked_by）和事件驱动触发。
Mailbox（邮箱）：RFC 0009，实现 Agent 间的消息传递机制，支持 pub/sub 订阅。
Registry（注册表）：RFC 0010，管理 Agent 的生命周期注册、存活检测和重启策略。
AgentFS（Agent 文件系统）：RFC 0011，为每个 Agent 进程提供独立的虚拟文件系统视图。
Kernel Store + Kernel Facade：通过 kernel/api.py 的 Kernel 统一 facade 类，将上述 9 个独立存储的初始化逻辑封装为单入口 Kernel.open(db_path)，极大降低了测试和集成的复杂度。

第四层：Daemon（守护进程）。 daemon/ 目录实现了完整的守护进程模式，包括：Agent 方法（通过 RPC 暴露）、Bridge 监督（自动重启 Telegram/WeChat/Slack 连接）、认证与权限、主动调度（proactive_scheduler）、会话管理、Spike 客户端等。F1-F9 的完整 Daemon 路线图已在 2026 年 5 月全部落地。

第五层：Tool System（工具系统）。 内置 27 种工具涵盖文件系统操作（Read/Write/Edit/Bash/Glob/Grep）、Web 能力（WebFetch/WebSearch）、Notebook 编辑、代码诊断、内存管理、子 Agent 调用、Skill 技能执行、任务管理（TaskCreate/Update/Get/List）、计划模式（EnterPlanMode/ExitPlanMode）等。工具通过 tool_registry.py 统一注册，支持 MCP 插件和 Git 插件的动态注入。

上手体验：零门槛安装 vs 深度定制

最简安装（推荐）：

curl -fsSL https://raw.githubusercontent.com/SafeRL-Lab/cheetahclaws/main/scripts/install.sh | bash
source ~/.zshrc
cheetahclaws

脚本自动检测操作系统（Linux/macOS/WSL2/Android Termux），创建独立 Python venv，安装核心依赖，配置 PATH，整个过程无需手动干预。2026 年 6 月 6 日的 v3.5.82 还专门修复了 macOS 上安装后 PATH 未正确写入 ~/.zshrc 的历史遗留 bug。

Web UI 部署（Docker 方式）：

cp .env.example .env  # 填写 API key
mkdir -p ./workspace ./data
docker compose up -d --build
# 打开 http://<host-ip>:8080/chat

Dockerfile 使用 python:3.13-slim，非 root 用户（UID 1000），通过 tini 处理 PID-1 信号，内置健康检查（每 30 秒检查 /api/config 返回状态）。docker-compose 挂载工作目录和配置目录，支持 Ollama 宿主机联动（通过 host.docker.internal），同时启动 Web UI 和 Telegram Bridge。

从源码直接运行：

pip install -e '.[all]'
python -m cheetahclaws

[all] 额外依赖组包含：语音（sounddevice）、视觉（Pillow）、浏览器自动化（playwright）、文档处理（pymupdf）、量化交易（yfinance + rank-bm25）等。

特色功能：从编程助手到全能 Agent 平台

CheetahClaws 早已超越了一个"本地 Claude Code 替代品"的定位，它的野心是成为一套通用的多模型 Agent 运行时平台。

Trading Agent（量化交易智能体）。 /trading 命令基于多智能体架构：analyst（分析师）研究市场数据 → researcher（研究员）收集宏观信息 → portfolio_manager（组合经理）计算配比 → risk_manager（风险管理）评估回撤。同时提供完整的回测引擎（backtest_strategy）、因子分析（factors）、异常检测（anomaly discovery）和板块轮动（sector_rotation）模块。

Research Lab（研究实验室）。 /research 将查询任务分发到 20 个信息源，包括 arXiv、HuggingFace Papers、Google Scholar、Semantic Scholar、OpenAlex、Polymarket、Reddit、HackerNews、Twitter、微博、小红书、知乎、Bilibili、SEC EDGAR 等，通过注意力热力图展示各源的信息权重，并支持趋势分析和多源对比。

Multi-Agent 多智能体编排。 支持通过 AgentCreate 创建子 Agent（类型可选：coder/reviewer/researcher 等），每个子 Agent 在独立的 git worktree 中运行（避免代码冲突），支持后台模式和与主 Agent 的消息传递。fanout.py 实现了任务广播——一个任务可以同时分发给多个专业 Agent 并行处理。

Bridges 桥接生态。 Telegram、微信（支持 smart_reply 智能回复）、Slack、QQ 均有官方 Bridge 实现，Bridge 接收消息后转发给 CheetahClaws 处理，结果通过同一 Channel 返回。Slack Bridge 支持 slash 命令透传（/research、/brainstorm），Telegram Bridge 支持 per-bridge 独立任务队列（!jobs/!retry/!cancel）。

上下文管理：四层协作的上下文压缩系统

长程任务中 Token 消耗是核心瓶颈。CheetahClaws 实现了一套四层协作的上下文压缩机制：

动态 max_tokens 上限（第一层）：每个模型有独立的上下文窗口注册表，系统根据当前已用 Token 比例实时调整下一轮回复的 max_tokens 上限。
AI Summarization（第二层）：在上下文达到 70% 阈值时，调用 AI 对早期对话进行摘要压缩。
智能截断 + 重写（第三层）：两层截断——先去掉工具输出的超长尾部（fanout），再在 70% 时触发 AI 压缩。
自动 fanout 控制（第四层）：对于超过 100 行的大文件，工具系统自动截断并标记。

v3.5.82 版本还引入了自适应 Markdown 流式输出（Adaptive Markdown Streaming），自动根据终端能力选择渲染模式：支持 ANSI 转义码的现代终端使用原地刷新，SSH/Apple Terminal/管道/CJK 文本使用追加提交，其他情况降级为纯文本。

安全加固：2026 年 5 月的两次 CRITICAL 修复

2026 年 5 月 12 日，项目进行了一次全面安全加固，修复了两个 CRITICAL 和多个 HIGH 级别漏洞：

环境变量令牌泄露：Bridge 配置中的 Bot Token 原本以明文存储在日志中，现改为仅记录引用（***REDACTED***）。
Web CSRF Cookie：Web UI 新增 CSRF 保护，AJAX 请求需携带 X-CSRF-Token 头。
Terminal Session 所有者绑定：每个终端会话与创建者 UID 绑定，防止跨用户劫持。
Plugin / MCP / Filesystem 沙箱：插件和 MCP 工具的权限边界重新定义，防止恶意插件提权。

2447 个安全相关测试用例全部通过。

行业意义：Harness Engineering 的崛起

CheetahClaws 的 GitHub 页面引用了一篇 arXiv 论文《Scaling the Harness》（arXiv:2605.26112），提出了"Harness Engineering"（线束工程）这一概念——类比传统汽车工程中"平台化线束"让不同车型共享零部件的思路，Harness Engineering 指的是构建一套与具体模型解耦的 Agent 基础设施，使同一套工具链、工作流和扩展生态可以在不同模型间自由切换。

随着 Claude、GPT-5、Gemini、DeepSeek R2 等模型的能力持续分化，开发者越来越需要一个"模型无关"的 Agent 框架来保护他们的工具链投资——今年用 Claude，明年换成 Qwen 或 DeepSeek，不需要重写任何工具、工作流和插件。CheetahClaws 正是这个方向上走得最远的开源实现之一。

开发团队： SafeRL-Lab（Safe AI and Robot Learning Lab，上海人工智能实验室相关），联系人 gushangding@gmail.com。项目采用 Apache-2.0 许可证，完全开源。