CodeWhale 使用说明书

说实话，第一感觉，看着不咋滴，但是耐不住好用呀！

1. 文档版本

• 文档名称：CodeWhale 使用说明书
• 版本号：1.0
• 生效日期：2026-06-21
• 编写人：自动生成

2. 概述

CodeWhale 是一个终端原生的 TUI 和 CLI 工具，面向开源与开权重模型的智能编程与任务调度。它可以启动交互式终端界面、执行自然语言命令、调用本地或远程模型、运行脚本、管理会话，并集成本地 Skill 工作流。

3. 适用场景

• 交互式编写代码与代码 review
• 本地/远程模型调用与调试
• 智能任务调度与工作流自动化
• 代码补全、生成与评审
• 与 VSCode、Python 工程、Skill 系统协同工作

4. 安装与准备

4.1 安装方式

1. 从 CodeWhale 官方仓库或发布渠道下载最新安装包。
2. 在 Windows 上使用可执行文件安装或直接解压。
3. 确保 codewhale 和 codewhale-tui 命令可以在命令行中访问。

4.2 环境准备

• 推荐使用 Windows 10/11、macOS 或 Linux。
• 安装 Python（如果使用 Python 扩展或 MCP 服务）。
• 配置 API Key（用于 DeepSeek、OpenAI、Hugging Face 等模型）。

4.3 配置文件

• 默认配置文件位于工作区路径下的 .codewhale/config.toml。
• 可通过 codewhale-tui setup 或手动创建配置。

5. 启动方式

5.1 交互式 TUI

codewhale-tui

该命令启动 CodeWhale 的终端交互界面，进入后一般会显示：

• 当前工作区路径
• 活动会话与历史记录
• 可用命令提示
• 当前模型与配置状态

你可以直接输入自然语言指令，也可以使用 CLI 子命令进行快速操作。TUI 支持会话持久化，重启后可继续上一次交互。

5.1.1 常见启动模式

• codewhale-tui：标准交互式启动。
• codewhale-tui --skip-onboarding：跳过首次引导页面，直接进入主会话。
• codewhale-tui --mouse-capture：启用 TUI 内部鼠标支持，可用于滚动、选中和拖动滚动条。
• codewhale-tui --no-mouse-capture：禁用鼠标捕获，使终端本身的文本选择正常工作。
• codewhale-tui --fresh：忽略上次会话恢复点，启动一个全新会话。

5.1.2 交互方式

• 输入文字并按回车提交请求。
• 通过 -p / --prompt 预先设置初始提示：

  codewhale-tui -p "请帮我分析这个目录下的 Python 脚本"
  

• 交互过程中，工具会保留上下文，便于后续连续询问。
• 若需要退出当前 TUI 会话，可按 Ctrl+C 或输入退出命令。

5.1.3 会话管理

• codewhale-tui sessions：列出已保存的会话记录及会话 ID。
• codewhale-tui resume <ID>：恢复指定会话。
• codewhale-tui resume --last：继续最近一次会话。
• codewhale-tui fork <ID>：基于历史会话创建一个新会话分支。

会话通常保存在工作区目录下的 .codewhale/sessions/ 中。使用会话管理可以保留上下文、复现实验和追踪历史操作。

5.2 CLI 命令

codewhale-tui [OPTIONS] [COMMAND]

例如：

codewhale-tui doctor
codewhale-tui exec --prompt "review this diff"

5.3 非交互式执行

codewhale-tui exec -p "请帮我生成测试用例" --auto

6. 常用命令说明

6.1 doctor

运行系统诊断并检查配置。

示例：

codewhale-tui doctor

6.2 setup

初始化 MCP 配置和 Skill 目录。

示例：

codewhale-tui setup

6.3 sessions

列出已保存会话。

示例：

codewhale-tui sessions

6.4 init

在当前目录创建默认 AGENTS.md。

示例：

codewhale-tui init

6.5 login / logout

管理 API Key。

示例：

codewhale-tui login
codewhale-tui logout

6.6 models

列出可用模型。

示例：

codewhale-tui models

6.7 exec

运行非交互式提示。

示例：

codewhale-tui exec --prompt "生成一段 Python 代码" --auto

6.8 pr

打开一个预先填充的 GitHub PR TUI。

示例：

codewhale-tui pr --help

6.9 apply

应用补丁文件到工作树。

示例：

codewhale-tui apply patch.diff

6.10 mcp

管理 MCP 服务器和相关服务。

示例：

codewhale-tui mcp status

7. 关键选项说明

• -p, --prompt <PROMPT>：初始提示文本，用于预设会话输入。
• --auto：自动执行工具支持命令，适合非交互式流程。
• --config <CONFIG>：指定配置文件路径。
• -v, --verbose：开启详细日志，调试问题时使用。
• -w, --workspace <WORKSPACE>：指定工作区目录，TUI 在该目录下操作文件和会话。
• -c, --continue：继续最近会话，恢复上次交互上下文。
• --resume <RESUME>：恢复指定会话 ID 或会话前缀。
• --fresh：启动全新会话，忽略恢复检查点和历史会话。
• --skip-onboarding：跳过首次引导界面，直接进入交互主界面。
• --mouse-capture：启用 TUI 内部鼠标支持，方便滚动和选择。
• --no-mouse-capture：禁用鼠标捕获，适合终端自身文本选择。
• --profile <PROFILE>：指定配置文件中的配置档案。
• --enable <FEATURE>：启用某个实验性或可选功能。
• --disable <FEATURE>：禁用某个功能。
• --no-project-config：跳过工作区级配置加载，仅使用全局配置。

7.1 TUI 运行模式建议

• 日常使用：直接运行 codewhale-tui 进入交互界面。
• 快速执行单条指令：codewhale-tui exec -p "..." --auto。
• 复用历史会话：codewhale-tui resume --last。
• 诊断系统与环境：codewhale-tui doctor。
• 调试时建议同时使用 -v 查看详细执行日志。

7.2 兼容配置说明

• .codewhale/config.toml：默认项目配置路径。
• --workspace 指定工作区后，TUI 会优先读取该目录下的 .codewhale 配置。
• --config 可直接指定一个配置文件，适合多个环境切换。

7.3 会话与恢复

• TUI 会话保存在 .codewhale/sessions/，包含交互历史和上下文信息。
• codewhale-tui sessions：列出可恢复的会话。
• codewhale-tui fork <ID>：从指定会话复制出一个新会话，便于并行实验。

8. CodeWhale 与 DeepSeek TUI 关系

• CodeWhale 是工具名称，原文档中对该工具的简称。
• codewhale-tui 是实际的终端命令入口，用于启动交互式 TUI 和执行 CLI 子命令。
• 在项目里，DeepSeek TUI 与 CodeWhale 可视为同一类型的调度入口，通常用于自然语言调度 Skill 和本地 Python 工程。

9. 项目与 Skill 集成

9.1 Skill 目录

• 将 *.skill 文件放入 .deepseek/skills/ 或项目指定的 Skill 目录中。
  -启动 codewhale-tui 时会自动扫描并加载这些 Skill。

9.2 Skill 调用

• 在 TUI 中输入自然语言指令，由 Skill 规则匹配并调用对应 Python 入口。
• 示例指令：
  • 分析 motor_test.dmd 并生成报告
  • 检索关键词 电池压差

9.3 工作流集成

• codewhale-tui 作为调度入口，将自然语言指令转换为 Skill 调用。
• Python 工程负责具体业务实现与数据处理。

10. 使用示例

10.1 基本启动

cd F:\EV_TEST_AI_WORKSPACE
codewhale-tui

10.2 直接执行提示

codewhale-tui exec -p "请生成 DMD 解析报告" --auto

10.3 诊断环境

codewhale-tui doctor

10.4 列出模型

codewhale-tui models

11. 常见问题

11.1 无法启动 codewhale-tui

• 检查命令是否在 PATH 中。
• 检查安装是否正确。
• 确认当前目录下是否存在 .codewhale/config.toml 或可被识别的工作区配置。

11.2 API Key 认证失败

• 重新执行 codewhale-tui login。
• 检查配置文件中的 API Key 是否正确。

11.3 Skill 未加载

• 确认 Skill 目录设置是否正确。
• 确认 *.skill 文件格式是否有效。
• 重新启动 codewhale-tui。

12. 附录

12.1 典型文件路径

• 工作区配置：.codewhale/config.toml
• Skill 目录：.deepseek/skills/
• 会话恢复：.codewhale/sessions/

12.2 参考命令

• codewhale-tui --help
• codewhale-tui doctor
• codewhale-tui sessions
• codewhale-tui exec --prompt "..."
• codewhale-tui mcp status

---

本说明书用于快速掌握 CodeWhale/CodeWhale TUI 的核心使用方式，具体参数与版本请结合实际 codewhale-tui --help 输出。