本章要解决的问题是如何安装CodeWhale，一个开源的终端编码助手。通过本章，你将能够在你的机器上安装CodeWhale，并开始使用它来提高编码效率。

首先，我们需要确保你的机器上已经安装了必要的工具和环境。具体来说，你需要有以下条件：

• 一个支持的操作系统（如Linux、macOS或Windows）
• 一个支持的Rust版本（如Rust 1.56或更高）
• 一个支持的终端（如bash、zsh或fish）

如果你已经满足了这些条件，我们可以开始安装CodeWhale。第一步是克隆CodeWhale的仓库：

git clone https://github.com/Hmbown/CodeWhale.git

这将会下载CodeWhale的源代码到你的机器上。

接下来，我们需要编译和安装CodeWhale。我们可以使用以下命令来完成这一步：

cd CodeWhale
cargo build --release

这将会编译CodeWhale的源代码，并生成一个可执行文件。

如果编译成功，我们可以使用以下命令来安装CodeWhale：

cargo install --path .

这将会安装CodeWhale到你的系统中。

完成后你已经得到了一个可用的CodeWhale安装。我们可以通过运行以下命令来验证CodeWhale是否已经安装成功：

codewhale --version

这应该会输出CodeWhale的版本号。

本章小结

• 克隆CodeWhale的仓库
• 编译和安装CodeWhale
• 验证CodeWhale是否已经安装成功
• 开始使用CodeWhale来提高编码效率

注意：如果你在安装过程中遇到任何问题，可以参考CodeWhale的文档和社区支持来解决问题。

本章的目标是帮助你初步了解CodeWhale的基本概念和使用方法。上一章我们已经成功安装了CodeWhale，现在我们可以开始探索它的功能了。

在开始使用CodeWhale之前，我们需要确保我们已经安装了必要的依赖项，并且CodeWhale的可执行文件已经添加到系统的PATH环境变量中。如果你在上一章完成了安装步骤，那么你已经满足了这些条件。

首先，我们来了解一下CodeWhale的基本概念。CodeWhale是一个终端编码助手，它支持多种模型和提供商。你可以将其视为一个工具，帮助你提高编码效率。CodeWhale的主要功能包括读取代码、执行编辑、运行命令、检查结果、规划多步任务和纠正错误。

现在，让我们来看看如何使用CodeWhale。我们可以通过运行以下命令来启动CodeWhale：

codewhale

这将会启动CodeWhale的终端界面，你可以在这里输入命令和参数来控制CodeWhale。

如果你想了解更多关于CodeWhale的命令和参数，可以运行以下命令：

codewhale --help

这将会输出CodeWhale的帮助信息，包括可用的命令和参数。

接下来，我们来看一下如何配置CodeWhale。CodeWhale的配置文件位于~/.codewhale/agent.json，你可以通过编辑这个文件来配置CodeWhale的行为。

例如，你可以通过添加以下配置来指定CodeWhale使用的模型：

{
  "model": "deepseek"
}

这将会告诉CodeWhale使用DeepSeek模型。

如果你遇到任何问题，可以参考CodeWhale的文档和社区支持来解决问题。

完成后你已经得到了一个基本的CodeWhale使用环境，并且了解了CodeWhale的基本概念和使用方法。

本章小结

• 了解CodeWhale的基本概念
• 启动CodeWhale的终端界面
• 了解CodeWhale的命令和参数
• 配置CodeWhale的行为
• 了解如何解决问题和获取帮助

配置CodeWhale：设置提供商和模型

本章的目标是配置CodeWhale的提供商和模型，确保CodeWhale能够正常工作并提供所需的功能。

前置条件

• 已经安装并启动CodeWhale
• 了解CodeWhale的基本概念和使用方法

配置提供商

CodeWhale支持多种提供商，包括DeepSeek、Claude、GPT、Kimi和GLM等。要配置提供商，需要修改~/.codewhale/agent.json文件。

{
  "provider": "deepseek"
}

这将会告诉CodeWhale使用DeepSeek提供商。

配置模型

CodeWhale支持多种模型，包括DeepSeek模型、open-weight模型等。要配置模型，需要修改~/.codewhale/agent.json文件。

{
  "model": "deepseek"
}

这将会告诉CodeWhale使用DeepSeek模型。

预期结果

配置提供商和模型后，CodeWhale将会使用指定的提供商和模型来提供功能。

常见报错与排查办法

• 如果配置文件格式不正确，CodeWhale将会输出错误信息。请检查配置文件格式并确保其正确。
• 如果提供商或模型不支持，CodeWhale将会输出错误信息。请检查提供商和模型是否支持。

实用技巧

• 可以使用codewhale --help命令来查看CodeWhale的帮助信息，包括可用的命令和参数。
• 可以使用codewhale --version命令来查看CodeWhale的版本信息。

小例子

假设我们想要使用DeepSeek提供商和DeepSeek模型来提供功能。我们可以修改~/.codewhale/agent.json文件如下：

{
  "provider": "deepseek",
  "model": "deepseek"
}

然后，我们可以启动CodeWhale并使用其提供的功能。

完成后你已经得到了一个配置好的CodeWhale环境，并且了解了如何配置CodeWhale的提供商和模型。

本章小结

• 了解CodeWhale的配置文件格式
• 配置CodeWhale的提供商和模型
• 了解配置提供商和模型的预期结果
• 掌握常见报错与排查办法
• 了解实用技巧和小例子

我们已经配置好了CodeWhale的提供商和模型，现在我们可以使用CodeWhale来执行复杂任务了。在这一章中，我们将学习如何使用CodeWhale来执行多步骤任务、运行命令、检查结果等。

首先，我们需要了解CodeWhale的任务执行机制。CodeWhale支持多种任务类型，包括代码编辑、命令运行、结果检查等。我们可以使用codewhale命令来执行任务，例如：

codewhale run my_task

这将执行名为my_task的任务。

其次，我们需要了解如何定义任务。CodeWhale支持多种任务定义方式，包括JSON文件、YAML文件等。我们可以使用以下命令来定义任务：

codewhale define my_task --file my_task.json

这将定义名为my_task的任务，使用my_task.json文件作为任务定义文件。

任务定义文件中，我们需要指定任务的类型、参数、依赖关系等。例如：

{
  "type": "code_edit",
  "params": {
    "file": "my_file.txt",
    "content": "Hello World!"
  },
  "depends": ["my_other_task"]
}

这定义了一个代码编辑任务，编辑my_file.txt文件，内容为Hello World!，并依赖于my_other_task任务。

我们也可以使用CodeWhale的内置函数来执行复杂任务。例如，我们可以使用codewhale.run_command函数来运行命令：

codewhale run_command "ls -l"

这将运行ls -l命令，并输出结果。

如果我们遇到错误，可以使用codewhale命令来查看错误信息：

codewhale error

这将输出错误信息。

在执行任务时，我们也可以使用CodeWhale的日志功能来查看任务执行日志：

codewhale log

这将输出任务执行日志。

常见报错与排查办法

• 如果任务定义文件格式不正确，CodeWhale将会输出错误信息。请检查任务定义文件格式并确保其正确。
• 如果任务依赖关系不正确，CodeWhale将会输出错误信息。请检查任务依赖关系并确保其正确。

实用技巧

• 可以使用codewhale --help命令来查看CodeWhale的帮助信息，包括可用的命令和参数。
• 可以使用codewhale --version命令来查看CodeWhale的版本信息。

小例子

假设我们想要执行一个代码编辑任务，编辑my_file.txt文件，内容为Hello World!。我们可以定义任务如下：

{
  "type": "code_edit",
  "params": {
    "file": "my_file.txt",
    "content": "Hello World!"
  }
}

然后，我们可以使用以下命令来执行任务：

codewhale run my_task

这将执行代码编辑任务，编辑my_file.txt文件，内容为Hello World!。

完成后你已经得到了一个可以执行复杂任务的CodeWhale环境，并且了解了如何定义任务、执行任务、查看错误信息和日志等。

本章小结

• 了解CodeWhale的任务执行机制
• 学会定义任务和执行任务
• 了解如何使用CodeWhale的内置函数来执行复杂任务
• 掌握常见报错与排查办法
• 了解实用技巧和小例子

本章要解决的问题是如何定制CodeWhale，包括修改配置和扩展功能。通过本章的学习，你将能够根据自己的需求定制CodeWhale，提高其使用效率。

前置条件是你已经安装并配置好了CodeWhale，并且了解了其基本使用方法。如果你还没有安装CodeWhale，可以参考前几章的内容。

我们先来看一下CodeWhale的配置文件agent.json。这个文件包含了CodeWhale的基本配置信息，包括其ID、名称、版本等。我们可以通过修改这个文件来定制CodeWhale的行为。

{
  "id": "codewhale",
  "name": "CodeWhale",
  "version": "0.8.65",
  // ...
}

接下来，我们可以通过添加或修改配置项来扩展CodeWhale的功能。例如，我们可以添加一个新的提供商或模型来支持更多的编程语言。

{
  "id": "codewhale",
  "name": "CodeWhale",
  "version": "0.8.65",
  "providers": [
    {
      "name": "DeepSeek",
      "url": "https://deepseek.com"
    },
    {
      "name": " Claude",
      "url": "https://claude.ai"
    }
  ]
}

如果你遇到配置文件修改失败或CodeWhale无法启动的问题，可以检查配置文件的格式和内容是否正确。同时，你也可以使用codewhale --help命令来查看CodeWhale的帮助信息，包括可用的命令和参数。

在扩展CodeWhale的功能时，我们需要注意保持代码的可读性和可维护性。我们可以通过添加注释和文档来说明代码的功能和用途。

# 添加一个新的提供商
codewhale provider add --name "New Provider" --url "https://new-provider.com"

完成后你已经得到了一个可以根据自己的需求定制的CodeWhale环境，并且了解了如何修改配置文件和扩展CodeWhale的功能。

本章小结

• 了解CodeWhale的配置文件agent.json和其内容
• 学会修改配置文件来定制CodeWhale的行为
• 了解如何添加或修改配置项来扩展CodeWhale的功能
• 掌握配置文件修改失败或CodeWhale无法启动的问题的排查方法
• 了解保持代码的可读性和可维护性的重要性

本章的目标是解决使用CodeWhale过程中可能遇到的常见问题和提高其性能。我们将一步步地探索如何排查和解决这些问题，确保CodeWhale能够稳定高效地运行。

首先，我们需要确保CodeWhale已经正确安装和配置。如果你还没有安装CodeWhale，可以按照以下命令进行安装：

npm install -g codewhale
codewhale --version   # 0.8.68

或者，你也可以使用cargo从源代码安装：

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

如果你已经安装了CodeWhale，但遇到了启动问题，可以尝试运行以下命令来检查CodeWhale的状态：

codewhale doctor

这个命令可以帮助你诊断和解决CodeWhale的常见问题。

如果你在使用CodeWhale的过程中遇到了问题，可以尝试检查以下几点：

• 配置文件是否正确：检查~/.codewhale/config.toml文件是否存在并且格式正确。
• 依赖项是否安装：确保所有必要的依赖项已经安装，例如Node.js和Rust。
• 网络连接是否正常：检查你的网络连接是否正常，确保可以访问CodeWhale的依赖服务。

如果你仍然无法解决问题，可以尝试查看CodeWhale的日志文件来获取更多信息：

codewhale --log-level debug

这个命令可以帮助你获取更多的调试信息。

为了提高CodeWhale的性能，你可以尝试以下几点：

• 优化配置文件：检查你的配置文件是否存在冗余或不必要的设置，优化后可以提高CodeWhale的性能。
• 使用缓存：CodeWhale提供了缓存功能，可以帮助提高性能。
• 更新依赖项：确保所有依赖项都是最新版本，可以帮助提高CodeWhale的性能。

完成后你已经得到了一个稳定高效的CodeWhale环境，并且了解了如何排查和解决常见问题。

本章小结

• 了解如何安装和配置CodeWhale
• 学会排查和解决CodeWhale的常见问题
• 了解如何提高CodeWhale的性能
• 掌握CodeWhale的调试和日志功能
• 了解如何优化配置文件和使用缓存来提高CodeWhale的性能

实战演练：使用CodeWhale完成真实项目

我们要解决的问题是如何使用CodeWhale来完成一个真实的项目。这个项目可以是一个简单的命令行工具，也可以是一个复杂的自动化系统。我们的目标是使用CodeWhale来自动化这个项目的开发和测试过程。

首先，我们需要确保CodeWhale已经正确安装和配置。我们可以通过运行以下命令来检查CodeWhale的版本：

codewhale --version

如果CodeWhale已经安装和配置正确，我们应该能够看到版本号。

接下来，我们需要创建一个新项目。我们可以使用CodeWhale的init命令来创建一个新项目：

codewhale init myproject

这个命令将创建一个新的项目目录，包含基本的项目结构和配置文件。

现在，我们需要配置CodeWhale来使用我们的项目。我们可以通过编辑agent.json文件来配置CodeWhale：

{
  "id": "myproject",
  "name": "My Project",
  "version": "1.0.0",
  "provider": "deepseek",
  "model": "my_model"
}

在这个例子中，我们配置CodeWhale来使用DeepSeek作为提供商，并使用my_model作为模型。

接下来，我们需要编写代码来实现我们的项目。我们可以使用CodeWhale的code命令来编写代码：

codewhale code myproject

这个命令将打开一个代码编辑器，我们可以在其中编写代码。

现在，我们需要测试我们的代码。我们可以使用CodeWhale的test命令来测试代码：

codewhale test myproject

这个命令将运行我们的代码并报告任何错误或问题。

如果我们遇到问题，我们可以使用CodeWhale的debug命令来调试代码：

codewhale debug myproject

这个命令将打开一个调试器，我们可以在其中调试代码。

完成后你已经得到了一个使用CodeWhale完成的真实项目，并且了解了如何使用CodeWhale来自动化开发和测试过程。

本章小结

• 了解如何使用CodeWhale来完成一个真实项目
• 学会配置CodeWhale来使用我们的项目
• 了解如何编写代码和测试代码使用CodeWhale
• 掌握CodeWhale的调试功能
• 了解如何使用CodeWhale来自动化开发和测试过程

本章要深入理解CodeWhale的内部原理和架构设计，通过了解其组件和工作流程，来掌握如何更好地使用和定制CodeWhale。

在开始之前，假设你已经安装并配置好了CodeWhale，并且对其基本使用方法有一定的了解。如果你还没有安装CodeWhale，可以参考前面的章节来完成安装和配置。

首先，我们来了解一下CodeWhale的架构设计。CodeWhale是一个终端编码助手，支持多种模型和提供商。它的架构设计可以分为以下几个部分：

• Agent：CodeWhale的核心组件，负责处理用户输入和执行任务。
• Provider：提供模型和数据的组件，CodeWhale支持多种提供商，包括DeepSeek、open-weight模型等。
• Task：CodeWhale执行的任务，包括代码生成、命令运行等。

我们可以通过以下命令来查看CodeWhale的版本和配置信息：

codewhale --version
codewhale --config

这将输出CodeWhale的版本和配置信息，包括提供商和模型的配置。

接下来，我们来了解一下CodeWhale的工作流程。CodeWhale的工作流程可以分为以下几个步骤：

1. 用户输入：用户输入任务和参数，CodeWhale接收并处理输入。
2. 任务执行：CodeWhale执行任务，包括代码生成、命令运行等。
3. 结果输出：CodeWhale输出任务执行结果。

我们可以通过以下代码来演示CodeWhale的工作流程：

import codewhale

# 创建一个新的任务
task = codewhale.Task("generate_code", "myproject")

# 设置任务的输入参数
task.input("language", "python")
task.input("framework", "flask")

# 执行任务
codewhale.run(task)

这将执行代码生成任务，并输出生成的代码。

在使用CodeWhale时，我们可能会遇到一些问题和错误。下面是一些常见的报错和排查办法：

• 配置文件错误：检查配置文件是否正确，是否存在语法错误。
• 提供商不支持：检查提供商是否支持当前的模型和任务。

通过了解CodeWhale的内部原理和架构设计，我们可以更好地使用和定制CodeWhale，来提高我们的编码效率。

本章小结

• 了解CodeWhale的架构设计和组件。
• 了解CodeWhale的工作流程和任务执行过程。
• 掌握常见的报错和排查办法。
• 了解如何使用CodeWhale来提高我们的编码效率。

问题：如何安装 CodeWhale？

安装 CodeWhale 可以通过多种方式，包括使用 npm、cargo、docker、nix、scoop 等。具体安装步骤请参考 INSTALL.md 文件。

问题：如何配置 CodeWhale？

配置 CodeWhale 可以通过运行 codewhale auth set 命令来设置提供商和模型。例如，运行 codewhale auth set --provider deepseek 来设置 DeepSeek 提供商。

问题：如何升级从 legacy deepseek-tui 包？

升级从 legacy deepseek-tui 包可以通过运行 codewhale doctor 命令来确认配置、会话、技能和 MCP 设置是否被保留。请参考 docs/REBRAND.md 文件。

问题：如何使用 CodeWhale 的 headless 模式？

使用 CodeWhale 的 headless 模式可以通过运行 codewhale exec 命令来执行脚本和 CI。例如，运行 codewhale exec --allowed-tools read_file,exec_shell --max-turns 10 "fix the failing test" 来执行一个脚本。

问题：如何选择提供商和模型？

选择提供商和模型可以通过运行 codewhale auth set 命令来设置提供商和模型。例如，运行 codewhale auth set --provider openrouter 来设置 OpenRouter 提供商。

问题：如何使用 CodeWhale 的路由解析器？

使用 CodeWhale 的路由解析器可以通过运行 codewhale 命令来解析一个真实的路由。路由解析器会根据提供商和模型来确定一个具体的端点、线协议、模型 ID、上下文限制和价格。

问题：如何显示路由的成本和使用情况？

显示路由的成本和使用情况可以通过运行 codewhale 命令来显示一个路由的成本状态。路由会报告一个具体的成本状态，包括每个 token 的价格、订阅/配额计量器、账户积分、本地/不适用 或 未知/过时。CodeWhale 永远不会编造一个它没有的价格。