1. 项目概述：CheetahClaws，一个为开发者而生的AI编码伴侣

如果你和我一样，每天在终端里敲代码的时间比在社交软件上聊天的时间还长，那你一定理解那种渴望——一个真正懂你、能无缝融入你工作流的AI助手。不是那种需要你打开浏览器、登录网页、复制粘贴代码的“外部工具”，而是一个能直接在你终端里运行、理解你的项目结构、甚至能帮你调试和重构代码的“搭档”。

这就是CheetahClaws诞生的初衷。它是一个纯Python实现的、轻量级的AI编码助手，灵感来源于Claude Code，但完全开源、可定制，并且支持几乎所有主流的大语言模型。你可以把它看作是一个“终端里的Claude Code”，但它更灵活、更透明，而且完全由你掌控。

我最初接触Claude Code时，被它的智能程度惊艳到了——它能理解复杂的代码上下文，能主动调用工具，能帮你完成从文件读写到代码诊断的一系列任务。但很快我就遇到了瓶颈：它只能使用Anthropic的API，而且代码是编译后的TypeScript包，将近300万行代码，想改点什么几乎不可能。更不用说，如果你想用本地的开源模型，或者想切换到GPT、Gemini等其他提供商，那根本就是天方夜谭。

于是，我决定自己动手。CheetahClaws的核心目标很简单：保留Claude Code最核心的“智能代理循环”——也就是AI能自主调用工具、完成任务的能力——但用Python重写，让它变得轻量、透明，并且支持任意模型。从最初的几百行代码原型，到现在的4万行完整实现，我花了大量时间打磨每一个细节，确保它既强大又易用。

现在，CheetahClaws已经成长为一个功能齐全的AI编码平台。它支持8+个模型提供商（包括Claude、GPT、Gemini、DeepSeek、Qwen等），能无缝对接本地模型（通过Ollama、vLLM或任何OpenAI兼容的端点）。它内置了27个核心工具，从基础的 Read 、 Write 、 Edit ，到高级的 NotebookEdit （直接操作Jupyter Notebook）、 GetDiagnostics （集成了pyright、mypy、flake8的代码诊断）。更重要的是，它的整个代理循环只有174行代码，完全开源，任何Python开发者都能在几分钟内理解、修改和扩展。

注意 ：CheetahClaws虽然灵感来自Claude Code，但它是一个独立的开源项目，与Anthropic官方没有任何关联。它完全由社区驱动，遵循MIT开源协议，你可以自由使用、修改和分发。

1.1 核心设计哲学：透明、可扩展、开发者友好

CheetahClaws的设计遵循几个核心原则，这些原则决定了它的使用体验和扩展能力：

透明性优先 ：整个系统的核心逻辑都在一个文件里（ agent.py ），代理循环清晰可见。工具注册、上下文管理、模型调用——所有关键部分都是纯Python，没有黑魔法。这意味着当你遇到问题时，你可以直接看代码，而不是猜测“系统到底在做什么”。

运行时扩展 ：你不需要重新编译或重启整个应用来添加新功能。通过 register_tool() 函数，你可以在运行时动态注册新工具。MCP（Model Context Protocol）服务器、Git插件、Markdown技能——所有这些都使用相同的机制，无缝集成到现有的工具生态中。

多模型支持作为一等公民 ：从项目第一天起，我就把多模型支持作为核心功能。CheetahClaws的模型抽象层让你可以轻松地在Claude、GPT、Gemini、DeepSeek等模型之间切换，只需要一个 --model 参数。对于本地模型，它原生支持Ollama的流式响应和工具调用，甚至能处理视觉输入（比如 llava 、 gemma4 模型）。

终端原生体验 ：CheetahClaws是为终端用户设计的。它支持Tab补全（输入 / 后按Tab可以看到所有命令及其描述）、多行粘贴（Bracketed Paste Mode确保你粘贴大段代码时不会出现空白行问题）、Rich库的实时Markdown渲染（当安装 rich 时，响应会以漂亮的格式流式显示）。还有 ! 命令前缀，让你可以直接执行Shell命令，而不需要AI介入。

让我举个例子说明这种设计哲学的实际价值。假设你正在调试一个复杂的Python项目，需要AI助手帮你分析代码。在CheetahClaws中，你可以：

# 启动CheetahClaws，使用本地模型
cheetahclaws --model ollama:qwen2.5-coder

# 在交互式REPL中，直接问它分析你的代码
/analyze my_project/

AI会调用 Read 工具读取文件，用 GetDiagnostics 运行静态分析，然后给出具体的建议。整个过程都在你的终端里完成，不需要切换到浏览器，不需要复制粘贴代码，AI完全在你的项目上下文中工作。

1.2 谁应该使用CheetahClaws？

基于我过去几个月的实际使用和社区反馈，我发现CheetahClaws特别适合以下几类用户：

独立开发者和技术爱好者 ：如果你经常在终端里工作，想要一个智能的编码助手来帮你写代码、调试、重构，但又不想被绑定到某个特定的云服务商，CheetahClaws是完美的选择。你可以用免费的本地模型（比如通过Ollama运行的 qwen2.5-coder ），也可以用付费的云模型（比如Claude 3.5 Sonnet），完全由你决定。

AI和LLM研究者 ：如果你在研究智能代理系统、工具调用、或者多模型协作，CheetahClaws的代码库是一个极佳的学习资源。整个代理循环只有174行，工具注册系统清晰明了，上下文管理策略完全可配置。你可以很容易地修改它来测试新的想法。

需要定制化AI工作流的团队 ：很多团队有特定的开发流程、代码规范、或者内部工具。CheetahClaws的插件系统和运行时工具注册让你可以轻松集成这些定制需求。比如，你可以添加一个工具来检查代码是否符合团队的lint规则，或者添加一个工具来自动生成API文档。

对隐私和安全性有要求的用户 ：因为CheetahClaws完全可以在本地运行（使用本地模型），你的代码和数据永远不会离开你的机器。这对于处理敏感代码或数据的场景特别重要。

想要摆脱“AI助手订阅制”的用户 ：很多AI编码助手都是按月收费的，而且功能受限。CheetahClaws是开源的，你可以免费使用，也可以根据自己的需求定制。如果你有技术能力，甚至可以自己部署云模型端点，完全控制成本和功能。

在接下来的章节中，我会详细拆解CheetahClaws的每一个核心功能，从安装配置到高级用法，从工具调用到多代理协作。我会分享我在实际使用中积累的经验、遇到的坑，以及如何最大化利用这个工具提升你的开发效率。

2. 核心架构解析：CheetahClaws如何工作

要真正用好CheetahClaws，你需要理解它的内部工作原理。这不仅能帮助你更好地使用它，还能在遇到问题时快速定位和解决。让我带你深入CheetahClaws的核心架构。

2.1 代理循环：AI如何思考和行动

CheetahClaws的核心是一个“代理循环”（Agent Loop），这个循环定义了AI如何接收用户输入、思考、调用工具、并生成响应的整个过程。与很多AI助手不同，CheetahClaws的代理循环是完全透明的——你可以在 agent.py 文件中看到完整的174行实现。

循环的基本流程 ：

1. 接收用户输入 ：当你在REPL中输入一个问题或指令时，CheetahClaws会将其添加到对话历史中。
2. 准备上下文 ：系统会收集当前工作目录的信息、git状态、持久化记忆（如果启用）、以及相关的文件内容，构建一个完整的上下文发送给模型。
3. 模型推理 ：模型接收上下文，分析用户意图，决定是否需要调用工具，或者直接生成回答。
4. 工具调用 ：如果模型决定调用工具，它会生成一个结构化的工具调用请求。CheetahClaws解析这个请求，找到对应的工具函数并执行。
5. 工具结果处理 ：工具执行的结果会被收集，并作为新的上下文信息发送回模型。
6. 生成最终响应 ：模型基于工具执行结果和之前的对话历史，生成最终的回答。
7. 更新对话历史 ：整个交互过程（用户输入、工具调用、模型响应）被保存到对话历史中，供后续交互参考。

这个循环会持续进行，直到模型认为任务完成，或者用户主动中断。

关键设计决策 ：

我选择使用Python的生成器（generator）来实现这个循环，而不是传统的回调或事件驱动模式。这样做有几个好处：

• 可读性 ：整个循环的逻辑在一个函数里，从上到下阅读，清晰明了。
• 可测试性 ：因为循环被封装在一个生成器中，你可以很容易地模拟输入、拦截输出，进行单元测试。
• 可扩展性 ：你可以在循环的任意位置插入钩子（hooks），比如在工具调用前后添加日志，或者修改模型的响应。

# 简化的代理循环示例（实际代码更复杂）
def agent_loop(initial_messages, tools, model):
    messages = initial_messages.copy()
    
    while True:
        # 调用模型，获取响应
        response = model.generate(messages, tools)
        
        # 处理模型的响应
        for event in response:
            if event.type == "text_chunk":
                yield TextChunk(event.content)
            elif event.type == "tool_call":
                # 执行工具
                tool_result = execute_tool(event.tool_name, event.arguments)
                # 将工具结果添加到消息中
                messages.append({
                    "role": "tool",
                    "content": tool_result,
                    "tool_call_id": event.tool_call_id
                })
                yield ToolEnd(event.tool_name, tool_result)
        
        # 检查是否应该继续
        if should_stop(messages):
            break

这种设计让CheetahClaws的代理循环既强大又灵活。你可以很容易地修改它来适应不同的需求，比如添加工具调用前的权限检查，或者修改上下文压缩的策略。

2.2 工具系统：AI的“手和眼”

工具是AI与外部世界交互的桥梁。在CheetahClaws中，每个工具都是一个 ToolDef 数据类的实例，包含名称、描述、参数模式和执行函数。

工具注册机制 ：

CheetahClaws使用一个全局的工具注册表。任何模块都可以在导入时调用 register_tool() 来注册新工具。这意味着：

• 内置工具 ：如 Read 、 Write 、 Edit 等，在启动时自动注册。
• MCP工具 ：如果你连接了MCP服务器，它的工具会自动注册到系统中。
• 插件工具 ：通过插件系统安装的工具也会自动注册。
• 自定义工具 ：你可以在运行时动态注册自己的工具，不需要重启应用。

工具的定义结构 ：

@dataclass
class ToolDef:
    name: str  # 工具名称，如"read_file"
    description: str  # 工具描述，用于模型理解工具用途
    parameters: dict  # JSON Schema格式的参数定义
    function: Callable  # 实际的执行函数
    read_only: bool = False  # 是否只读工具（影响权限检查）
    concurrent_safe: bool = True  # 是否支持并发调用

工具调用的实际流程 ：

当模型决定调用工具时，它会生成一个类似这样的JSON：

{
  "tool_call_id": "call_123",
  "name": "read_file",
  "arguments": {
    "path": "/path/to/file.py"
  }
}

CheetahClaws解析这个JSON，找到对应的 ToolDef ，验证参数，然后调用 function 。工具执行的结果会被格式化为字符串，发送回模型作为后续推理的输入。

为什么工具系统如此重要？

在我实际使用中，工具系统的设计直接影响了AI的能力边界。一个好的工具应该：

1. 有明确的边界 ：每个工具只做一件事，并且做好。比如 Read 工具只负责读取文件内容，不负责解析或分析。
2. 提供足够的上下文 ：工具的描述和参数文档要足够详细，让模型能正确理解何时以及如何使用这个工具。
3. 处理错误 gracefully ：工具执行可能失败（文件不存在、权限不足等），工具函数应该捕获这些异常并返回有意义的错误信息，而不是让整个代理循环崩溃。

CheetahClaws内置的27个工具覆盖了开发中的常见需求，但真正的力量在于它的可扩展性。你可以很容易地添加自定义工具来适应你的特定工作流。

2.3 上下文管理：在有限token内保持智能

所有大语言模型都有上下文窗口的限制。即使是拥有100万token的Gemini 2.0，如果你无限制地添加对话历史，最终也会达到上限。CheetahClaws采用了一个两层的上下文压缩策略，确保在长时间对话中保持智能。

第一层：基于规则的截断（无API成本）

这是最直接的压缩方式。当对话历史超过一定长度时，CheetahClaws会：

1. 保留最近的N轮对话（通过 preserve_last_n_turns 参数配置，默认是10轮）。
2. 对于更早的对话，如果包含工具调用的输出，这些输出会被截断或完全移除。
3. 只保留工具调用的摘要或关键结果。

这个策略基于一个观察：在长时间的编码会话中，早期的工具输出（比如文件内容、命令输出）往往已经不再相关。保留它们只会占用宝贵的token空间。

第二层：AI驱动的摘要（有API成本）

当基于规则的截断还不够时，CheetahClaws会调用模型本身来生成摘要。具体来说：

1. 系统会选择最旧的、仍然相关的对话轮次。
2. 将这些轮次的内容发送给模型，要求生成一个简洁的摘要。
3. 用摘要替换原始内容，显著减少token使用。

这个摘要过程是智能的——模型会保留关键信息，比如重要的决策、代码变更、或者用户明确要求记住的内容。

配置上下文压缩 ：

你可以通过 /config 命令调整上下文压缩的行为：

# 设置保留最近15轮完整对话
/config preserve_last_n_turns 15

# 查看当前的上下文设置
/config

实际使用中的经验 ：

在我的使用中，我发现默认的压缩策略在大多数情况下都工作得很好。但有几个特殊情况需要注意：

• 长时间调试会话 ：如果你在调试一个复杂的问题，可能需要参考很早之前的错误信息。在这种情况下，你可以临时增加 preserve_last_n_turns 的值，或者手动使用 /compact 命令来触发一次性的压缩。
• 代码审查场景 ：当AI在审查大量代码时，工具输出（文件内容）可能会占用大量token。这时，启用更积极的压缩策略是有帮助的。
• 记忆系统的作用 ：CheetahClaws的记忆系统（ MemorySave / MemorySearch 工具）可以缓解上下文限制的问题。重要的信息可以保存到记忆中，而不是一直保留在对话历史里。

2.4 记忆系统：让AI记住重要的事情

记忆系统是CheetahClaws中一个强大但容易被忽视的功能。与Claude Code的自动记忆提取不同，CheetahClaws采用了一种更可控、更可审计的方法。

记忆的类型 ：

CheetahClaws支持四种类型的记忆：

1. 事实（Fact） ：客观信息，如“项目的数据库使用PostgreSQL 15”。
2. 决策（Decision） ：重要的决定和理由，如“选择FastAPI而不是Flask，因为需要异步支持和自动API文档”。
3. 偏好（Preference） ：用户或项目的偏好，如“代码风格使用Black格式化，行宽88字符”。
4. 待办（Todo） ：需要后续处理的事项。

每个记忆都包含丰富的元数据：

• content ：记忆内容
• type ：记忆类型
• confidence ：置信度（0.0-1.0）
• source ：来源（哪个工具或用户创建的）
• created_at ：创建时间
• last_used_at ：最后使用时间
• conflict_group ：冲突组标识（用于检测冲突记忆）

记忆的创建和使用 ：

记忆不是自动创建的。AI必须显式调用 MemorySave 工具来保存记忆，或者用户可以通过 /memory save 命令手动添加。这样做有几个好处：

• 可控性 ：你可以精确控制什么被记住，什么不被记住。
• 可审计性 ：每个记忆都有明确的来源和时间戳，你可以追溯它的创建过程。
• 减少幻觉 ：因为记忆是显式创建的，AI不太可能“记住”一些它实际上不知道的事情。

当AI需要相关信息时，它可以调用 MemorySearch 工具。搜索算法会考虑：

1. 查询与记忆内容的相关性（基于文本相似度）
2. 记忆的置信度
3. 记忆的新鲜度（ last_used_at 时间）
4. 是否属于同一冲突组（避免返回相互冲突的记忆）

记忆的冲突检测 ：

这是CheetahClaws记忆系统的一个独特功能。当保存新记忆时，系统会检查是否与现有记忆冲突：

# 简化的冲突检测逻辑
def detect_conflict(new_memory, existing_memories):
    for mem in existing_memories:
        if same_topic(new_memory, mem) and contradictory(new_memory, mem):
            # 标记为冲突
            new_memory.conflict_group = mem.conflict_group or generate_group_id()
            mem.conflict_group = new_memory.conflict_group
            return True
    return False

冲突的记忆会被分组，搜索时会优先返回最近使用过的、或者置信度更高的那个。

记忆合并 ：

你可以使用 /memory consolidate 命令手动触发记忆合并。这个过程：

1. 找出相关的记忆（基于内容和冲突组）
2. 让AI分析这些记忆，生成一个合并后的版本
3. 删除旧的记忆，保存合并后的新记忆

这个功能特别有用当项目需求发生变化，或者早期的一些决策被推翻时。

实际使用技巧 ：

基于我的经验，这里有一些使用记忆系统的最佳实践：

1. 在项目开始时建立基础记忆 ：当你开始一个新项目时，手动添加一些基础记忆，比如技术栈选择、项目结构、编码规范等。这能让AI从一开始就“理解”你的项目上下文。

2. 让AI主动保存重要决策 ：当你和AI讨论并做出重要技术决策时，提示它“请将这个决策保存到记忆中”。比如：“我们决定使用SQLAlchemy ORM而不是直接写SQL，因为需要更好的类型安全和迁移支持。请保存这个决策。”

3. 定期审查和清理记忆 ：使用 /memory list 查看所有记忆，删除过时或不准确的记忆。使用 /memory consolidate 合并相似或冲突的记忆。

4. 利用记忆进行上下文切换 ：如果你在多个项目间切换，记忆系统能帮助AI快速“回想”起每个项目的特定信息，而不需要你重新解释。

5. 注意记忆的置信度 ：当AI保存记忆时，它会给出一个置信度。低置信度的记忆（比如基于猜测或不确定的信息）应该谨慎对待。你可以通过 /memory edit 命令手动调整置信度。

记忆系统可能是CheetahClaws中最像“真正智能”的部分。它让AI不仅仅是处理当前任务，还能积累知识，在长时间的合作中变得越来越懂你和你的项目。

3. 安装与配置：从零开始搭建你的AI助手

现在让我们进入实战环节。我会带你完成CheetahClaws的完整安装和配置过程，分享一些我在不同环境中部署的经验和避坑指南。

3.1 系统要求与环境准备

CheetahClaws设计为跨平台运行，支持macOS、Linux和Windows（通过WSL或原生Python）。以下是基本要求：

Python版本 ：需要Python 3.8或更高版本。我推荐使用Python 3.10或3.11，它们在性能和兼容性方面都有很好的表现。

操作系统 ：

• macOS ：10.15 (Catalina) 或更高版本
• Linux ：任何现代发行版（Ubuntu 20.04+, CentOS 8+, Fedora 34+等）
• Windows ：Windows 10/11，通过WSL 2运行Ubuntu，或者原生Python（某些功能可能受限）

内存和存储 ：

• 基础运行：至少512MB RAM
• 使用本地模型：取决于模型大小，通常需要4GB+ RAM
• 磁盘空间：500MB用于安装和依赖

网络 ：如果需要使用云API模型（Claude、GPT、Gemini等），需要稳定的网络连接。对于纯本地运行，网络不是必须的。

先检查你的环境 ：

在开始安装前，先确认你的Python环境：

# 检查Python版本
python3 --version
# 应该显示 Python 3.8 或更高

# 检查pip是否可用
python3 -m pip --version

# 检查git（用于从源码安装）
git --version

如果系统中有多个Python版本，我强烈建议使用虚拟环境（venv）来隔离CheetahClaws的依赖。这能避免与系统或其他项目的Python包冲突。

3.2 安装方法详解：选择最适合你的方式

CheetahClaws提供了多种安装方式，每种都有其适用场景。我会详细介绍每一种方法，并给出我的推荐。

3.2.1 一键安装脚本（推荐给大多数用户）

这是最简单快捷的安装方式，特别适合想要快速上手的用户。安装脚本会自动处理所有依赖和配置。

# 使用curl下载并执行安装脚本
curl -fsSL https://raw.githubusercontent.com/SafeRL-Lab/cheetahclaws/main/scripts/install.sh | bash

这个脚本会：

1. 检查系统环境（Python版本、pip等）
2. 创建虚拟环境（可选，但推荐）
3. 安装CheetahClaws及其核心依赖
4. 将 cheetahclaws 命令添加到你的PATH中
5. 创建默认配置文件

安装完成后，你需要重新加载shell配置：

# 对于zsh用户（macOS默认）
source ~/.zshrc

# 对于bash用户
source ~/.bashrc

# 对于fish用户
source ~/.config/fish/config.fish

然后就可以启动了：

cheetahclaws

注意 ：一键安装脚本会修改你的shell配置文件（.zshrc或.bashrc）。如果你对系统配置比较谨慎，可以先查看脚本内容：

curl -fsSL https://raw.githubusercontent.com/SafeRL-Lab/cheetahclaws/main/scripts/install.sh

或者使用下面更可控的安装方式。

3.2.2 使用pip安装（适合Python老手）

如果你已经熟悉Python的包管理，或者想要更精细地控制安装过程，可以使用pip：

# 创建并激活虚拟环境（推荐）
python3 -m venv ~/.cheetahclaws-venv
source ~/.cheetahclaws-venv/bin/activate

# 安装CheetahClaws
pip install cheetahclaws

# 如果需要Web UI支持
pip install 'cheetahclaws[web]'

# 如果需要语音功能
pip install 'cheetahclaws[voice]'

# 如果需要所有额外功能
pip install 'cheetahclaws[all]'

使用虚拟环境的好处是隔离性。你可以在不同的虚拟环境中安装不同版本的CheetahClaws，或者单独管理它的依赖。

激活虚拟环境后，直接运行：

cheetahclaws

如果你不想每次都用 source 激活虚拟环境，可以创建一个alias：

# 添加到 ~/.zshrc 或 ~/.bashrc
alias cc='source ~/.cheetahclaws-venv/bin/activate && cheetahclaws'

这样只需要输入 cc 就可以启动CheetahClaws了。

3.2.3 使用uv安装（最快的Python包管理器）

uv 是一个用Rust写的极速Python包管理器。如果你需要频繁安装或更新包，uv能显著加快速度：

# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用uv安装CheetahClaws
uv pip install cheetahclaws

# 或者从源码安装
git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws
uv sync

uv的优势在于：

• 极快的依赖解析和下载
• 更好的缓存机制
• 与pip完全兼容
• 内置虚拟环境管理

对于需要频繁切换Python项目或依赖很多包的用户，uv是很好的选择。

3.2.4 从源码运行（适合开发者或贡献者）

如果你想直接参与开发，或者想要最新的未发布功能，可以从源码运行：

# 克隆仓库
git clone https://github.com/SafeRL-Lab/cheetahclaws.git
cd cheetahclaws

# 安装依赖
pip install -r requirements.txt

# 如果需要可选功能
pip install -r requirements-web.txt  # Web UI
pip install -r requirements-voice.txt  # 语音功能

# 直接运行
python -m cheetahclaws.main

# 或者安装为可编辑模式
pip install -e .
cheetahclaws

从源码运行让你可以：

• 随时查看和修改代码
• 使用最新的开发分支功能
• 更容易调试和贡献代码
• 运行测试套件

3.2.5 Docker安装（适合容器化环境）

如果你更喜欢使用Docker，或者需要在隔离的环境中运行：

# 拉取镜像
docker pull ghcr.io/saferl-lab/cheetahclaws:latest

# 运行容器
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.cheetahclaws:/root/.cheetahclaws \
  -e OPENAI_API_KEY=your_key_here \
  ghcr.io/saferl-lab/cheetahclaws:latest

Docker方式的好处是环境完全一致，不受宿主机Python环境的影响。但需要注意文件挂载和API密钥的传递。

3.3 配置API密钥和模型

安装完成后，你需要配置至少一个模型的API密钥才能开始使用。CheetahClaws支持多种配置方式，从简单到复杂。

3.3.1 环境变量配置（推荐）

这是最灵活的方式，特别适合已经在使用其他AI工具的用户：

# 设置OpenAI API密钥
export OPENAI_API_KEY="sk-..."

# 设置Anthropic API密钥
export ANTHROPIC_API_KEY="sk-ant-..."

# 设置Google Gemini API密钥
export GEMINI_API_KEY="AIza..."

# 设置DeepSeek API密钥
export DEEPSEEK_API_KEY="sk-..."

# 设置Moonshot (Kimi) API密钥
export MOONSHOT_API_KEY="sk-..."

# 设置MiniMax API密钥
export MINIMAX_API_KEY="sk-..."

# 设置智谱AI (Zhipu) API密钥
export ZHIPU_API_KEY="..."

你可以把这些export命令添加到你的shell配置文件（ ~/.zshrc 、 ~/.bashrc 等）中，这样每次启动终端时都会自动设置。

3.3.2 配置文件方式

CheetahClaws也会在 ~/.cheetahclaws/config.json 中查找配置。你可以手动创建这个文件：

{
  "openai_api_key": "sk-...",
  "anthropic_api_key": "sk-ant-...",
  "gemini_api_key": "AIza...",
  "model": "gpt-4o",
  "temperature": 0.7,
  "max_tokens": 4000
}

配置文件的好处是可以保存更多设置，而不仅仅是API密钥。但注意，配置文件中的敏感信息（API密钥）是以明文存储的，请确保文件权限安全：

chmod 600 ~/.cheetahclaws/config.json

3.3.3 交互式配置向导

如果你不确定如何配置，或者想快速测试，CheetahClaws提供了交互式配置向导：

# 启动配置向导
cheetahclaws --config-wizard

# 或者启动后使用命令
cheetahclaws
/config wizard

向导会一步步引导你：

1. 选择主要使用的模型提供商
2. 输入API密钥
3. 设置默认模型
4. 配置其他偏好（温度、最大token数等）

3.3.4 验证配置

配置完成后，你可以验证是否设置正确：

# 启动CheetahClaws并测试连接
cheetahclaws --test

# 或者在REPL中测试
cheetahclaws
/test connection

如果一切正常，你会看到类似这样的输出：

✓ OpenAI API: Connected (gpt-4o available)
✓ Anthropic API: Connected (claude-3-5-sonnet available)
✓ Gemini API: Connected (gemini-2.0-flash available)

3.3.5 模型选择策略

CheetahClaws支持众多模型，如何选择？基于我的经验，这里有一些建议：

对于日常编码任务 ：

• 平衡型 ： gpt-4o 或 claude-3-5-sonnet - 良好的编码能力和推理能力的平衡
• 经济型 ： gpt-4o-mini 或 claude-3-5-haiku - 成本更低，速度更快，适合简单任务
• 本地型 ： ollama:qwen2.5-coder - 完全离线，隐私最好

对于复杂推理和规划 ：

• 最强能力 ： claude-3-5-opus - 最强大的推理能力，适合复杂系统设计
• 长上下文 ： gemini-2.0-flash (1M token) - 处理超长文档或代码库
• 本地推理 ： ollama:deepseek-r1 - 本地推理模型，支持深度思考

对于特定领域 ：

• 中文任务 ： qwen-plus 或 ollama:qwen2.5 - 对中文理解更好
• 代码生成 ： deepseek-coder 系列 - 专门为代码训练
• 多模态 ： gpt-4o 或 gemini-2.0-flash - 支持图像输入

你可以在运行时随时切换模型：

# 启动时指定模型
cheetahclaws --model gpt-4o

# 或者在REPL中切换
/model gpt-4o

3.3.6 本地模型配置（Ollama）

如果你选择使用本地模型，需要先安装和配置Ollama：

# 安装Ollama（Linux/macOS）
curl -fsSL https://ollama.ai/install.sh | sh

# 下载一个模型
ollama pull qwen2.5-coder

# 启动Ollama服务（通常会自动启动）
ollama serve

# 在CheetahClaws中使用
cheetahclaws --model ollama:qwen2.5-coder

Ollama的优势：

• 完全离线 ：不需要网络连接
• 隐私安全 ：数据不出本地
• 成本为零 ：没有API费用
• 可定制 ：可以加载自己的模型或调整参数

但需要注意：

• 硬件要求 ：较大的模型需要足够的RAM（7B模型约需14GB，13B模型约需26GB）
• 速度 ：取决于你的硬件，可能比云API慢
• 能力 ：大多数开源模型的能力仍落后于顶尖的闭源模型

3.4 常见安装问题与解决方案

在帮助社区用户安装CheetahClaws的过程中，我积累了一些常见问题的解决方案：

问题1：Python版本不兼容

Error: CheetahClaws requires Python 3.8 or higher

解决 ：升级Python，或使用pyenv管理多个Python版本：

# 使用pyenv安装Python 3.11
pyenv install 3.11.0
pyenv global 3.11.0

问题2：权限错误（Permission denied）

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

解决 ：不要使用sudo安装Python包。使用虚拟环境或用户安装：

# 用户安装（不推荐长期使用）
pip install --user cheetahclaws

# 或使用虚拟环境（推荐）
python -m venv venv
source venv/bin/activate
pip install cheetahclaws

问题3：依赖冲突

ERROR: Cannot install cheetahclaws because these package versions have conflicting dependencies.

解决 ：这是Python包管理的经典问题。尝试：

1. 使用全新的虚拟环境
2. 使用uv安装（更好的依赖解析）
3. 手动安装有冲突的包的不同版本

问题4：API密钥验证失败

Error: Invalid API key for OpenAI

解决 ：

1. 确认API密钥是否正确复制（注意开头结尾的空格）
2. 确认API密钥是否有足够的额度或权限
3. 尝试在浏览器中访问API提供商的控制台，确认密钥有效
4. 对于OpenAI，可以这样测试：

   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer YOUR_API_KEY"
   

问题5：网络连接问题

ConnectionError: Failed to establish a new connection

解决 ：

1. 检查网络连接
2. 如果是中国用户，可能需要配置代理（注意：仅用于访问国际API，不用于其他用途）
3. 尝试使用国内模型（如DeepSeek、Qwen、Zhipu）
4. 或者使用本地模型（Ollama）

问题6：内存不足（使用本地模型时）

CUDA out of memory

解决 ：

1. 使用更小的模型（如 qwen2.5:1.5b 而不是 qwen2.5:7b ）
2. 增加交换空间（swap）
3. 使用CPU模式（速度较慢）：

   ollama run qwen2.5-coder --num-gpu 0
   

4. 量化模型（使用GGUF格式的4bit或8bit量化版本）

问题7：启动后无响应

# 启动后卡住，没有显示REPL

解决 ：

1. 检查是否有其他进程占用了相同端口
2. 尝试增加超时时间：

   cheetahclaws --timeout 30
   

3. 查看详细日志：

   cheetahclaws --verbose
   

4. 重置配置文件：

   rm -rf ~/.cheetahclaws
   

安装和配置是使用任何工具的第一步，也是最重要的一步。花点时间确保环境正确设置，能避免后续使用中的很多问题。一旦配置完成，你就可以开始探索CheetahClaws的强大功能了。

4. 核心功能深度解析

CheetahClaws的功能非常丰富，从基础的代码编辑到高级的多代理协作，从本地语音输入到云端会话同步。在这一章，我会深入讲解最重要的几个功能，分享实际使用中的技巧和最佳实践。

4.1 代码编辑与诊断：AI如何理解你的代码

作为编码助手，CheetahClaws最核心的能力就是理解和操作代码。这主要通过几个内置工具实现：

4.1.1 文件操作三剑客：Read、Write、Edit

Read工具 ：读取文件内容。看起来简单，但有几个细节需要注意：

# AI调用Read工具的示例
{
  "tool_call_id": "call_123",
  "name": "read_file",
  "arguments": {
    "path": "./src/main.py",
    "start_line": 10,  # 可选：从第10行开始
    "end_line": 50     # 可选：到第50行结束
  }
}

使用技巧 ：

• 当文件很大时，指定 start_line 和 end_line 可以节省token
• 对于二进制文件（如图片、PDF），Read工具会返回Base64编码
• 支持相对路径和绝对路径，但AI更习惯使用相对路径（基于当前工作目录）

Write工具 ：创建新文件或覆盖现有文件。这是AI实现代码生成的主要方式。

# AI调用Write工具的示例
{
  "tool_call_id": "call_124",
  "name": "write_file",
  "arguments": {
    "path": "./src/utils.py",
    "content": "def calculate_sum(numbers):\n    return sum(numbers)\n",
    "overwrite": true  # 可选：是否覆盖已存在文件
  }
}

重要注意事项 ：

• 默认情况下，如果文件已存在，Write工具会失败（安全考虑）
• 设置 overwrite: true 可以覆盖现有文件
• 对于重要文件，建议先备份或让AI先读取现有内容

Edit工具 ：这是最强大的工具，允许AI像人类一样编辑文件——插入、删除、替换特定行。

# AI调用Edit工具的示例
{
  "tool_call_id": "call_125",
  "name": "edit_file",
  "arguments": {
    "path": "./src/main.py",
    "edits": [
      {
        "type": "replace",
        "start_line": 20,
        "end_line": 25,
        "new_content": "    # 新的实现\n    result = process_data(data)\n    return result\n"
      },
      {
        "type": "insert",
        "line": 30,
        "content": "    # 添加日志记录\n    logger.info('Processing completed')\n"
      },
      {
        "type": "delete",
        "start_line": 35,
        "end_line": 40
      }
    ]
  }
}

Edit工具的优势 ：

1. 精确性 ：可以精确到行级别的修改
2. 可读性 ：生成的diff清晰易懂（CheetahClaws会用git风格的+/-显示变更）
3. 安全性 ：每次编辑都会显示预览，需要用户确认（除非在 auto 权限模式下）

实际使用经验 ：

• 对于小的修改（几行代码），Edit工具比Write工具更合适
• 对于大的重构，建议先让AI生成完整的文件内容，再用Write工具创建新文件
• 编辑前最好先让AI读取文件，确保它理解当前代码结构
• 使用 /diff 命令可以查看未保存的修改

4.1.2 GetDiagnostics：集成的代码诊断

这是CheetahClaws的一个杀手级功能。 GetDiagnostics 工具集成了多个代码分析器，为AI提供全面的代码质量反馈。

支持的分析器 ：

• pyright ：Microsoft的Python类型检查器
• mypy ：另一个流行的Python类型检查器
• flake8 ：Python代码风格检查
• py_compile ：Python内置的语法检查
• tsc ：TypeScript编译器（如果项目中有TypeScript）
• shellcheck ：Shell脚本检查器

工作流程 ：

1. AI调用 GetDiagnostics 工具，指定文件或目录
2. CheetahClaws依次运行所有可用的分析器
3. 收集所有错误、警告和建议
4. 格式化结果返回给AI

# AI调用GetDiagnostics的示例
{
  "tool_call_id": "call_126",
  "name": "get_diagnostics",
  "arguments": {
    "path": "./src/",  # 可以检查单个文件或整个目录
    "linters": ["pyright", "flake8"]  # 可选：指定使用哪些分析器
  }
}

为什么这很重要 ： 在传统的AI编码助手中，AI只能看到代码的文本内容。有了 GetDiagnostics ，AI还能看到：

• 类型错误（Type errors）
• 语法错误（Syntax errors）
• 代码风格问题（Style violations）
• 潜在bug（Potential bugs）

这使得AI不仅能写代码，还能 理解代码的问题 。比如，AI可以：

• 修复类型错误
• 改进代码风格
• 发现潜在的逻辑错误
• 提供具体的改进建议

配置技巧 ： 你可以在项目根目录创建配置文件，定制分析器的行为：

# pyrightconfig.json
{
  "typeCheckingMode": "strict",
  "pythonVersion": "3.10"
}

# .flake8
[flake8]
max-line-length = 88
extend-ignore = E203

CheetahClaws会自动发现并使用这些配置文件。

4.1.3 NotebookEdit：直接操作Jupyter Notebook

对于数据科学家和研究人员，Jupyter Notebook是日常工作的重要工具。CheetahClaws的 NotebookEdit 工具允许AI直接操作 .ipynb 文件，无需启动Jupyter内核。

支持的操作 ：

• 添加单元格 ：在指定位置插入新的代码或Markdown单元格
• 删除单元格 ：删除一个或多个单元格
• 替换单元格 ：替换单元格的内容
• 执行单元格 ：运行代码单元格并捕获输出（需要内核）
• 重新排序单元格 ：调整单元格的顺序

# AI调用NotebookEdit的示例
{
  "tool_call_id": "call_127",
  "name": "notebook_edit",
  "arguments": {
    "path": "./analysis.ipynb",
    "operations": [
      {
        "type": "insert_cell",
        "index": 3,
        "cell_type": "code",
        "content": "# 新增的数据预处理步骤\ndf_cleaned = df.dropna()\ndf_cleaned.head()"
      },
      {
        "type": "replace_cell",
        "index": 5,
        "new_content": "# 更新可视化代码\nimport matplotlib.pyplot as plt\nplt.figure(figsize=(10, 6))\nplt.plot(df_cleaned['x'], df_cleaned['y'])\nplt.title('Updated Visualization')\nplt.show()"
      }
    ]
  }
}

使用场景 ：

1. 自动化数据流水线 ：AI可以读取数据、清理数据、进行分析、生成可视化，全部在一个Notebook中完成
2. 教学材料生成 ：AI可以创建包含解释和示例的教学Notebook
3. 报告生成 ：结合数据分析和Markdown单元格，生成完整的数据报告
4. 代码重构 ：将杂乱的Notebook重构为结构清晰的版本

注意事项 ：

• NotebookEdit直接操作JSON，不执行代码。如果需要执行，AI可以调用Bash工具运行 jupyter nbconvert --execute
• 对于大型Notebook，建议先让AI读取部分内容，避免token超限
• 修改前最好备份原文件

4.1.4 Bash和Glob：文件系统操作

虽然 Read / Write / Edit 工具能处理文件内容，但有时AI需要操作文件系统本身。这就是 Bash 和 Glob 工具的用武之地。

Bash工具 ：执行Shell命令

{
  "tool_call_id": "call_128",
  "name": "bash",
  "arguments": {
    "command": "find . -name '*.py' -type f | head -20",
    "timeout": 30  # 可选：超时时间（秒）
  }
}

使用技巧 ：

• 对于长时间运行的任务，设置合理的 timeout
• AI应该优先使用更安全的工具（如 Glob 查找文件），只在必要时使用 Bash
• 复杂的命令应该分解为多个简单的命令，便于错误处理

Glob工具 ：查找文件模式

{
  "tool_call_id": "call_129",
  "name": "glob",
  "arguments": {
    "pattern": "**/*.py",
    "exclude": ["**/test_*.py", "**/__pycache__/**"]
  }
}

为什么用Glob而不是Bash的find ：

1. 跨平台 ：Glob使用Python的 glob 模块，在Windows和Unix上行为一致
2. 更安全 ：不会执行任意Shell命令
3. 更精确 ：支持复杂的排除模式
4. 集成更好 ：结果直接以结构化数据返回

实际工作流示例 ： 假设AI需要分析一个Python项目：

# 1. 首先用Glob找到所有Python文件
{
  "name": "glob",
  "arguments": {"pattern": "**/*.py"}
}

# 2. 选择几个关键文件用Read读取
{
  "name": "read_file",
  "arguments": {"path": "./src/main.py"}
}

# 3. 运行诊断
{
  "name": "get_diagnostics",
  "arguments": {"path": "./src/"}
}

# 4. 如果需要，用Bash运行测试
{
  "name": "bash",
  "arguments": {"command": "pytest tests/ -v"}
}

这种组合使用工具的方式，让AI能够像人类开发者一样探索和理解代码库。

4.2 多代理协作：让多个AI一起工作

单个AI的能力有限，但多个AI协作可以解决更复杂的问题。CheetahClaws的多代理系统允许你创建专门化的AI助手，让它们各司其职，共同完成任务。

4.2.1 代理类型系统

CheetahClaws内置了几种代理类型，每种都有不同的专长：

1. coder ：编码专家，擅长写代码、调试、重构
2. reviewer ：代码审查专家，擅长发现bug、改进代码质量
3. researcher ：研究专家，擅长搜索信息、分析资料
4. writer ：写作专家，擅长文档、报告、文章
5. debugger ：调试专家，擅长定位和修复复杂bug
6. architect ：架构专家，擅长系统设计、技术选型

你可以创建自定义代理类型，只需定义相应的提示词和工具集。

4.2.2 创建和使用代理

创建代理 ：

# 在REPL中创建代理
/agent create --type coder --name "python-expert"

# 或者通过工具调用
{
  "tool_call_id": "call_130",
  "name": "agent",
  "arguments": {
    "action": "create",
    "type": "reviewer",
    "name": "code-reviewer",
    "config": {
      "model": "gpt-4o",  # 可选：指定代理使用的模型
      "temperature": 0.3,  # 可选：更确定的输出
      "tools": ["read_file", "get_diagnostics"]  # 可选：限制可用的工具
    }
  }
}

代理的工作方式 ：

• 每个代理在独立的上下文中运行，有自己的对话历史
• 代理可以访问主会话的部分上下文（通过配置决定）
• 代理之间可以通过 SendMessage 工具通信
• 主AI可以委托任务给代理，并等待结果

实际案例：代码审查流水线

假设你写了一个新功能，想要全面的代码审查：

# 主AI（协调者）的工作流：
# 1. 创建审查代理
{
  "name": "agent",
  "arguments": {
    "action": "create",
    "type": "reviewer",
    "name": "security-reviewer",
    "config": {"focus": "security"}
  }
}

# 2. 创建另一个审查代理
{
  "name": "agent",
  "arguments": {
    "action": "create",
    "type": "reviewer", 
    "name": "performance-reviewer",
    "config": {"focus": "performance"}
  }
}

# 3. 将代码发送给安全审查代理
{
  "name": "send_message",
  "arguments": {
    "agent_name": "security-reviewer",
    "message": "请审查以下代码的安全问题：\n```python\n# 代码内容...\n```"
  }
}

# 4. 同时发送给性能审查代理
{
  "name": "send_message",
  "arguments": {
    "agent_name": "performance-reviewer",
    "message": "请审查以下代码的性能问题：\n```python\n# 代码内容...\n```"
  }
}

# 5. 收集结果
{
  "name": "check_agent_result",
  "arguments": {"agent_name": "security-reviewer"}
}

{
  "name": "check_agent_result", 
  "arguments": {"agent_name": "performance-reviewer"}
}

# 6. 综合两个代理的反馈，生成最终建议

代理的优势 ：

• 专业化 ：每个代理可以专注于特定领域
• 并行化 ：多个代理可以同时工作，提高效率
• 隔离性 ：代理的错误不会影响主会话
• 可重用性 ：创建好的代理可以保存和重复使用

4.2.3 代理通信模式

代理之间可以通过几种模式通信：

1. 请求-响应模式 ：主AI向代理发送请求，等待响应
2. 发布-订阅模式 ：代理可以向特定主题发布消息，其他代理订阅这些主题
3. 工作流模式 ：代理按顺序处理任务，每个代理的输出是下一个代理的输入

示例：三阶段代码生成

# 阶段1：架构师设计系统
architect_agent = create_agent("architect", "sys-designer")
send_message(architect_agent, "设计一个用户认证系统")

# 阶段2：编码员实现代码
architect_result = check_agent_result(architect_agent)
coder_agent = create_agent("coder", "implementer")
send_message(coder_agent, f"根据以下设计实现代码：\n{architect_result}")

# 阶段3：审查员检查代码
coder_result = check_agent_result(coder_agent)
reviewer_agent = create_agent("reviewer", "inspector")
send_message(reviewer_agent, f"审查以下代码：\n{coder_result}")

# 综合所有结果
final_result = combine_results(architect_result, coder_result, reviewer_result)

4.2.4 代理管理最佳实践

基于我的使用经验，这里有一些代理管理的最佳实践：

1. 明确代理职责

• 给每个代理清晰的职责描述
• 在创建代理时指定 focus 或 expertise 参数
• 限制代理可用的工具，避免权限过大

2. 控制代理成本

• 为代理使用更经济的模型（如 gpt-4o-mini 而不是 gpt-4o ）
• 设置代理的token限制
• 及时清理不再需要的代理

3. 监控代理状态

• 使用 /agents list 查看所有运行中的代理
• 定期检查代理的对话历史，确保它们没有偏离主题
• 设置超时，避免代理无限运行

4. 设计有效的协作流程

• 定义清晰的输入输出格式
• 使用模板确保一致性
• 为主AI设计协调逻辑，处理代理间的冲突

5. 保存和重用代理配置

• 将成功的代理配置保存为模板
• 为常见任务创建预配置的代理
• 使用 /agent save 和 /agent load 命令

多代理系统是CheetahClaws最强大的功能之一，但也需要精心设计才能发挥最大价值。开始时可以从简单的两个代理协作入手，逐渐增加复杂度。

4.3 记忆与上下文管理

在长时间的工作会话中，如何让AI记住重要的信息是一个挑战。CheetahClaws的记忆系统提供了解决方案。

4.3.1 记忆的类型和使用场景

事实记忆（Fact）

• 用途 ：存储客观信息，如项目配置、技术栈、API端点等
• 示例 ："本项目使用FastAPI框架，运行在端口8000"
• 最佳实践 ：在项目开始时，手动添加关键事实记忆

决策记忆（Decision）

• 用途 ：记录重要的技术决策和理由
• 示例 ："选择PostgreSQL而不是MySQL，因为需要JSONB支持和更好的GIS功能"
• 最佳实践 ：每当做出架构或技术选择时，让AI保存决策记忆

偏好记忆（Preference）

• 用途 ：记录个人或团队的编码偏好
• 示例 ："代码格式化使用black，行宽88字符，使用双引号"
• 最佳实践 ：这些记忆帮助AI生成符合团队规范的代码

待办记忆（Todo）

• 用途 ：记录需要后续处理的任务
• 示例 ："需要添加用户认证的单元测试"
• 最佳实践 ：与 /worker 命令结合，实现任务自动化

4.3.2 记忆的创建和检索

手动创建记忆 ：

# 在REPL中直接创建
/memory save --type fact --content "项目使用Python 3.10和FastAPI"

# 或者通过工具
{
  "tool_call_id": "call_131",
  "name": "memory_save",
  "arguments": {
    "type": "decision",
    "content": "使用SQLAlchemy ORM而不是原始SQL，为了更好的类型安全和迁移支持",
    "confidence": 0.9,
    "tags": ["database", "orm", "decision"]
  }
}

让AI自动创建记忆 ： 你可以指示AI在对话中自动保存重要信息：

用户：我们决定使用Redis作为缓存层，因为它的性能比Memcached更好，而且支持更多数据结构。

AI：好的，我已经将这个决策保存到记忆中。
{
  "name": "memory_save",
  "arguments": {
    "type": "decision",
    "content": "使用Redis作为缓存层，因为性能比Memcached更好，且支持更多数据结构",
    "confidence": 0.8,
    "tags": ["cache", "redis", "architecture"]
  }
}

搜索记忆 ：

# 搜索所有与数据库相关的记忆
/memory search database

# 通过工具搜索
{
  "tool_call_id": "call_132",
  "name": "memory_search",
  "arguments": {
    "query": "缓存策略",
    "limit": 5,
    "min_confidence": 0.7
  }
}

搜索算法详解 ： CheetahClaws使用基于BM25的搜索算法，考虑以下因素：

1. 文本相关性 ：查询与记忆内容的匹配程度
2. 置信度 ：高置信度的记忆排名更高
3. 新鲜度 ：最近使用过的记忆排名更高（ last_used_at 字段）
4. 冲突组 ：避免返回相互冲突的记忆

4.3.3 记忆冲突与合并

当有多个相关但可能冲突的记忆时，CheetahClaws能检测并处理：

冲突检测 ：

# 当保存新记忆时，系统自动检测冲突
new_memory = MemorySave(
    type="fact",
    content="API速率限制是1000次/小时",
    confidence=0.9
)

# 系统发现已有冲突记忆：
# 记忆1: "API速率限制是500次/小时" (confidence=0.8, last_used=2天前)
# 记忆2: "API速率限制是1000次/小时" (confidence=0.7, last_used=1小时前)

# 结果：新记忆与记忆1冲突，两者被标记为同一冲突组

手动合并记忆 ：

# 查看冲突的记忆
/memory list --conflict

# 手动合并
/memory consolidate --group conflict_123

合并过程 ：

1. 系统收集同一冲突组的所有记忆
2. 让AI分析这些记忆，生成一个合并后的版本
3. 删除旧的冲突记忆，保存新的合并记忆
4. 更新相关记忆的引用

4.3.4 记忆系统的实际应用

场景1：新成员加入项目 当新成员（或新的AI会话）加入项目时，可以快速加载关键记忆：

# 加载项目记忆
/memory load --scope project

# 搜索特定主题的记忆
/memory search "认证系统"
/memory search "数据库模式"
/memory search "部署流程"

这相当于给AI一个"项目速成课"，让它快速理解项目上下文。

场景2：长期项目维护 在长达数周或数月的项目中，记忆系统帮助保持一致性：

# 每周回顾和清理记忆
/memory list --sort-by last_used
# 删除过时的记忆
/memory delete --id old_memory_id

# 合并相似的记忆
/memory consolidate --auto

场景3：多AI协作 当多个AI代理协作时，它们可以共享记忆：

# 代理A保存记忆
{
  "name": "memory_save",
  "arguments": {
    "type": "fact",
    "content": "用户服务API响应时间平均为120ms",
    "scope": "project"  # 项目级记忆，所有代理可见
  }
}

# 代理B可以检索这个记忆
{
  "name": "memory_search", 
  "arguments": {
    "query": "API响应时间",
    "scope": "project"
  }
}

场景4：知识积累 将解决问题的经验保存为记忆，形成知识库：

问题：如何处理数据库连接池耗尽？
解决方案：增加最大连接数，添加连接超时，实现连接健康检查。
相关代码：utils/database.py中的ConnectionPool类。
保存为记忆：数据库连接池管理最佳实践。

下次遇到类似问题时，AI可以直接从记忆中获取解决方案。

4.3.5 记忆系统的限制和注意事项

记忆不是万能的 ：

• 记忆系统基于文本相似度搜索，对于复杂概念的匹配可能不准确
• 记忆的置信度是主观的，需要定期审查
• 记忆不会自动更新，当事实变化时需要手动更新

最佳实践 ：

1. 定期维护 ：每周花几分钟审查和清理记忆
2. 明确标签 ：为记忆添加清晰的标签，便于搜索
3. 控制数量 ：不要保存太多低价值的记忆，避免搜索噪音
4. 验证重要记忆 ：对于关键信息，定期验证其准确性
5. 使用合适的范围 ：用户级记忆 vs 项目级记忆

性能考虑 ：

• 记忆数量过多会影响搜索速度
• 考虑使用 /memory export 定期备份，然后清理旧记忆
• 对于大型团队，可能需要分项目的记忆存储

记忆系统是CheetahClaws中让AI显得更"智能"的功能之一。通过精心维护记忆库，你可以让AI助手真正理解你的项目和工作方式，而不仅仅是响应单个查询。

4.4 高级功能：SSJ模式、研究管道与交易代理

除了核心的编码功能，CheetahClaws还提供了一些高级功能，能够显著提升工作效率。这些功能体现了"智能代理"的真正潜力——不仅仅是执行命令，而是理解上下文、制定计划、并自主执行复杂工作流。

4.4.1 SSJ开发者模式：一站式工作流引擎

SSJ（Simple and Smart Job）模式是CheetahClaws的"超级菜单"，将15个常用工作流集成在一个交互式界面中。启动SSJ模式：

/ssj

你会看到一个编号菜单，每个选项对应一个完整的工作流：

SSJ Developer Mode - Power Menu
================================
1.  Brainstorm - 多专家头脑风暴
2.  TODO Viewer - 查看待办列表
3.  Worker - 自动执行待办任务
4.  Expert Debate - 专家辩论
5.  Propose - 提案生成
6.  Review - 代码审查
7.  Readme - README生成
8.  Commit - 提交助手
9.  Scan - 代码扫描
10. Promote - 推广内容生成
11. Video Factory - 视频生成流水线
12. TTS Factory - 文本转语音
13. Monitor - 监控订阅
14. Trading - 交易分析
15. Agent - 自主代理
16. Research - 多源研究
17. Trend Track - 趋势跟踪
18. Reports - 报告管理

输入编号或命令，/exit退出，/help查看帮助

核心工作流详解 ：

1. Brainstorm（头脑风暴） 这是我最常用的功能之一。当你面对一个复杂问题或新项目时，Brainstorm模式可以：

• 生成2-100个专家角色（默认5个），每个角色有不同专长
• 组织迭代式辩论，让专家们从不同角度讨论问题
• 自动生成"Master Plan"总结
• 创建具体的待办列表（ brainstorm_outputs/todo_list.txt ）

# 启动头脑风暴
/ssj
1
# 或直接
/brainstorm "设计一个分布式任务队列系统"

# 控制专家数量
/brainstorm "微服务架构设计" --experts 8

# 指定输出目录
/brainstorm "AI代码审查工具" --output ./my_plan/

实际案例 ：当我需要设计一个新的数据管道时，我使用Brainstorm生成了5个专家：系统架构师、数据工程师、DevOps专家、安全专家、成本优化专家。他们的辩论帮助我发现了单点故障风险、数据一致性问题和潜在的安全漏洞，这些我在最初设计中都忽略了。

2. Worker（自动执行） Worker模式读取 todo_list.txt 中的任务，并自动执行：

# 查看待办列表
/ssj
2

# 自动执行所有待办任务
/ssj
3

# 选择特定任务执行
/worker 1,3,5  # 执行第1、3、5个任务

# 限制同时工作的Worker数量
/worker --workers 2  # 最多2个任务并行

Worker的智能之处在于：

• 每个任务使用专门的提示词，确保高质量完成
• 自动标记已完成的任务（ [x] ）
• 支持任务依赖关系
• 失败的任务会重试或报告

3. Expert Debate（专家辩论） 与Brainstorm类似，但更专注于深度技术辩论：

# 启动专家辩论
/debate "React vs Vue vs Svelte for a new dashboard project"

# 指定正反方专家
/debate "Microservices vs Monolith" --pro "微服务专家" --con "单体架构专家"

# 设置辩论轮数
/debate "SQL vs NoSQL" --rounds 5

Expert Debate会生成结构化的辩论记录，包括：

• 各方论点
• 证据和示例
• 反驳和回应
• 最终裁决和建议

4. Research（多源研究） 这是信息收集的利器，同时查询20+个来源：

# 基础研究
/research "大语言模型推理优化技术"

# 带时间范围
/research "区块链扩容方案" --range 6m

# 特定日期范围
/research "Web3安全漏洞" --since 2024-01-01 --until 2024-06-30

# 扩展查询（自动生成子查询）
/research "边缘计算" --expand

# 比较多个主题
/research compare "React" vs "Vue" vs "Svelte"

研究管道的输出包括 ：

• 综合简报 ：所有来源的整合分析
• 跨平台热度表 ：显示每个主题在不同平台的讨论热度
• 实体提取 ：自动识别关键人物、组织、模型、基准测试
• 出版趋势图 ：12个月的学术发表趋势
• 高引作者分析 ：识别该领域的权威研究者
• 并排比较 ：多个主题的对比分析

支持的20+数据源 ：

• 学术：arXiv、Semantic Scholar、OpenAlex、HuggingFace Papers、alphaXiv、Google Scholar
• 技术社区：HackerNews、GitHub、Reddit、StackOverflow
• 新闻：Google News、Reuters、BBC、AP
• 市场：Polymarket、SEC EDGAR
• 搜索：Tavily、Brave、Twitter/X
• 中文平台：知乎、B站、微博、小红书

5. Trading Agent（交易代理） 对于需要市场分析的用户，Trading Agent提供了完整的分析流水线：

# 分析单个股票
/trading analyze AAPL

# 分析加密货币
/trading analyze BTC

# 多资产分析
/trading analyze "AAPL,TSLA,MSFT"

# 运行回测
/trading backtest --strategy momentum --symbol AAPL --period 1y

交易分析流程 ：

1. 数据收集 ：获取价格、基本面、新闻、社交媒体情绪
2. 多头/空头研究 ：两个AI研究员分别从看涨和看跌角度分析
3. 研究裁判 ：第三个AI评估双方论点的质量
4. 风险管理委员会 ：激进、保守、中性三个风险偏好的AI评估风险
5. 投资组合经理 ：综合所有分析，给出最终建议（买入/增持/持有/减持/卖出）

回测策略 ：

• 动量策略（Momentum）
• 均值回归（Mean Reversion）
• 突破策略（Breakout）
• 多因子策略（Multi-factor）

6. Monitor（监控订阅） 自动监控你关心的主题，定期推送更新：

# 启动监控向导
/monitor

# 订阅AI研究更新
/subscribe research:llm-optimization weekly

# 订阅股票监控
/subscribe stock:AAPL daily

# 订阅加密货币
/subscribe crypto:BTC 4h

# 订阅自定义新闻
/subscribe custom:"quantum computing breakthroughs" daily

监控系统在后台运行，通过Telegram、Slack或控制台推送更新。这对于跟踪竞争对手、技术趋势或投资机会特别有用。

4.4.2 SSJ模式的高级用法

持久化会话 ： SSJ模式的一个关键特性是持久化。你可以在不同工作流间切换，而不会丢失上下文：

# 启动SSJ
/ssj

# 进行头脑风暴
1
# ... 完成头脑风暴

# 回到SSJ主菜单（按Ctrl+C或输入/exit）

# 查看生成的待办列表
2

# 执行任务
3

# 需要研究某个技术细节时
16
/research "gRPC负载均衡策略"

命令穿透 ： 在SSJ模式下，你仍然可以使用所有常规命令：

/ssj
# 在SSJ中直接切换模型
/model gpt-4o

# 保存会话
/save

# 查看成本
/cost

自定义工作流 ： 你可以创建自己的SSJ工作流模板：

# 创建自定义模板
echo '{
  "name": "代码审查流水线",
  "steps": [
    {"type": "brainstorm", "topic": "代码审查最佳实践"},
    {"type": "review", "path": "./src/"},
    {"type": "worker", "tasks": "brainstorm_outputs/todo_list.txt"}
  ]
}' > ~/.cheetahclaws/ssj_templates/code_review.json

# 在SSJ中使用自定义模板
/ssj --template code_review

4.4.3 实际应用案例

案例1：从零开始一个新项目

# 1. 启动SSJ模式
/ssj

# 2. 头脑风暴项目设计
1
"构建一个实时股票分析平台，使用FastAPI、WebSocket和机器学习"

# 3. 查看生成的待办列表
2

# 4. 自动执行架构设计任务
3 --workers 3

# 5. 研究关键技术选型
16
/research "实时数据流处理框架比较" --expand

# 6. 专家辩论重要决策
4
/debate "Kafka vs Redis Streams vs RabbitMQ for real-time analytics"

# 7. 生成项目README
7

案例2：技术债务清理周

# 1. 扫描代码问题
/ssj
9
/scan --path ./src/ --linters all

# 2. 头脑风暴重构方案
1
"重构 monolithic service to microservices"

# 3. 自动执行重构任务
3 --workers 2

# 4. 监控重构后的性能
13
/monitor
/subscribe custom:"service response time" hourly

# 5. 生成重构报告
18
/reports generate --type refactoring --period "last week"

案例3：投资研究流程

# 1. 研究行业趋势
/research "electric vehicle battery technology" --range 1y --citations

# 2. 分析相关公司
/trading analyze "TSLA, BYD, NIO, LI"

# 3. 设置监控
/subscribe stock:TSLA daily
/subscribe research:ev-battery weekly
/subscribe crypto:BTC 4h

# 4. 定期查看报告
/reports list --type research
/reports open latest

SSJ模式将CheetahClaws从一个被动的编码助手，转变为一个主动的工作流引擎。它理解你的意图，分解复杂任务，协调多个专家，并自动执行——这正是"智能代理"应有的样子。

5. 集成与扩展：连接外部世界

CheetahClaws的强大不仅在于其内置功能，更在于它的可扩展性。通过MCP集成、插件系统、以及各种桥接器，你可以将CheetahClaws连接到几乎任何系统。

5.1 MCP集成：扩展AI的能力边界

MCP（Model Context Protocol）是一个开放协议，允许AI模型访问外部工具和数据源。CheetahClaws原生支持MCP，这意味着你可以连接任何MCP服务器，立即获得新的工具能力。

5.1.1 MCP基础概念

MCP服务器 ：提供工具和数据源的独立进程。例如：

• 文件系统服务器：访问本地文件
• 数据库服务器：查询数据库
• 浏览器服务器：控制网页浏览器
• 日历服务器：访问日历事件

MCP工具 ：服务器提供的具体功能，每个工具都有：

• 名称和描述
• 输入参数模式（JSON Schema）
• 执行函数

传输协议 ：MCP支持多种传输方式：

• stdio：标准输入输出（最简单）
• SSE：服务器发送事件（用于HTTP服务器）
• HTTP：普通的HTTP请求

5.1.2 连接MCP服务器

通过配置文件连接 ：

在 ~/.cheetahclaws/mcp_servers.json 中配置：

{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "env": {}
    },
    {
      "name": "sqlite",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-sqlite", "/home/user/data.db"],
      "env": {}
    },
    {
      "name": "github",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  ]
}

通过命令连接 ：

# 连接一个MCP服务器
/mcp connect filesystem --command npx --args @modelcontextprotocol/server-filesystem /home/user/projects

# 查看已连接的服务器
/mcp list

# 查看服务器提供的工具
/mcp tools filesystem

# 断开连接
/mcp disconnect filesystem

5.1.3 使用MCP工具

一旦