| 1 | <!-- source: README.md sha256:ebf1c69de0dc --> |
| 2 | # Codewhale |
| 3 | |
| 4 | Codewhale 是一款开源智能体，可使用你选择的托管模型或本地模型读取项目、编辑文件、运行命令并检查自己的工作。从终端中的一项任务开始。对于较大的工作，可以将其中的部分任务交给使用不同模型、承担不同角色的智能体。 |
| 5 | |
| 6 |  |
| 7 | |
| 8 | *终端预览截图来自 v0.9.12 的开发构建。* |
| 9 | |
| 10 | [English](README.md) · [日本語](README.ja-JP.md) · [Tiếng Việt](README.vi.md) · [Bahasa Indonesia](README.id.md) · [한국어](README.ko-KR.md) · [Español](README.es-419.md) · [Português](README.pt-BR.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [繁體中文](README.zh-TW.md) · [हिन्दी](README.hi.md) · [Türkçe](README.tr.md) · [Italiano](README.it.md) · [Polski](README.pl.md) · [العربية](README.ar.md) · [Català](README.ca.md) |
| 11 | |
| 12 | [](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml) |
| 13 | [](https://crates.io/crates/codewhale-cli) |
| 14 | [](https://www.npmjs.com/package/codewhale) |
| 15 | [](https://discord.gg/37gfS3ksug) |
| 16 | |
| 17 | ## 安装 |
| 18 | |
| 19 | macOS / Linux：推荐安装官方 GitHub Release。 |
| 20 | |
| 21 | ```bash |
| 22 | curl -fsSL https://codewhale.net/install.sh | sh |
| 23 | "$HOME/.local/bin/codewhale" |
| 24 | ``` |
| 25 | |
| 26 | 安装器会选择最新的已发布版本。[更新日志](CHANGELOG.md)也描述了下一版本尚未发布的候选构建；只有在该版本正式发布后，已发布的下载包才会包含这些变更。 |
| 27 | |
| 28 | Windows 请使用 [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases/latest) |
| 29 | 中的安装器或压缩包。已有的直接安装使用 `codewhale update`；它会显示当前可执行文件路径， |
| 30 | 并保留比已发布版本更新的构建。npm 和 Cargo 是次要打包选项。 |
| 31 | 迁移与 PATH 排查见[安装指南](docs/zh_hans/INSTALL.md)。 |
| 32 | |
| 33 | 首次运行会帮助你连接提供商，也可以离线配置 Codewhale。要获得模型回复，必须连接托管模型或本地模型。Codewhale 还支持 npm 和 Cargo 作为次要打包方式，以及 Docker、Nix、Scoop、Android/Termux 和可选的 CNB 镜像。对于现有的软件包管理器安装，系统会提供迁移说明。请参阅[安装与 PATH 帮助](docs/INSTALL.md)。 |
| 34 | |
| 35 | 每种 shell 只需一条命令即可启用 Tab 补全——`codewhale completion bash|zsh|fish|powershell|elvish`。请参阅 [shell 补全](docs/INSTALL.md#8-shell-completions)。 |
| 36 | |
| 37 | ## 使用 |
| 38 | |
| 39 | 在项目文件夹中打开终端并运行 `codewhale`。使用 `/provider` 选择提供商，使用 `/model` 选择模型，然后描述一项具体任务： |
| 40 | |
| 41 | ```text |
| 42 | Fix the failing tests and explain what changed. |
| 43 | ``` |
| 44 | |
| 45 | 也可以不打开 TUI，直接运行任务： |
| 46 | |
| 47 | ```bash |
| 48 | codewhale exec "fix the failing tests and explain what changed" |
| 49 | ``` |
| 50 | |
| 51 | Codewhale 可以读取你的代码仓库、编辑文件、运行命令、检查结果，并持续推进目标。使用 `/mode plan` 可以在不修改文件、不执行 shell 命令的情况下进行探索；希望它实施修改时，使用 `/mode work`。按 `Shift+Tab` 可选择 Ask、Auto-Review 或 Full Access；[模式与权限指南](docs/MODES.md)说明了各自允许的操作。 |
| 52 | |
| 53 | ## 终端、应用与 Computer Use |
| 54 | |
| 55 | 终端和图形客户端连接到 Codewhale Runtime，由它运行智能体及其工具： |
| 56 | |
| 57 | - **终端：** `codewhale` 打开交互界面；`codewhale exec` 可从脚本或 CI 作业中运行任务。 |
| 58 | - **本地浏览器：** `codewhale web` 打开随附的[本地 Web 客户端](docs/WEB.md)，使用同一个 Runtime。 |
| 59 | - **Codewhale 桌面应用（GPUI）：** 原生 GPUI 桌面应用是产品客户端方向（2026-09-14 决定；阶段规划见私有 codehwhale-gpui 仓库中的 docs/TRANSITION.md）。app.codewhale.net 的托管网页应用将分阶段下线；营销站点、登录、计费、法律和下载页面永久保留在网页上。其可用情况见[产品页面](https://codewhale.net/en/product)。 |
| 60 | |
| 61 | **Computer Use 提供观察其他应用并与之交互的工具。** 当前源码已包含此插件。使用前请查看它请求的访问权限并启用它；仍须满足操作系统权限和平台要求。请参阅随附的 [Computer Use 指南](crates/tui/plugins/computer-use/README.md)和[插件设置](docs/PLUGINS.md)。 |
| 62 | |
| 63 | 在 VS Code 中，社区维护的 CodeWhale 扩展通过侧边栏连接本地 Runtime。可从 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=HengQuWorld.brotherwhale-vscode) 安装；源码见 [GitHub](https://github.com/HengQuWorld/CodeWhale-VSCode)。 |
| 64 | |
| 65 | ## 为什么选择 Codewhale |
| 66 | |
| 67 | - **选择你的模型。** 连接托管提供商，或通过 Ollama、vLLM、SGLang 使用本地模型。使用 `/provider` 切换提供商，使用 `/model` 选择模型。 |
| 68 | - **掌控始终在你手中。** 检查拟执行的操作及其造成的文件变更。审批设置决定何时需要审查；Full Access 仍须遵守不可逾越的策略边界。`/undo` 和 `/restore` 可帮助恢复工作区变更。 |
| 69 | - **让长时间任务井然有序。** 保存会话、设置持久的 `/goal`、在工作流运行前进行审查，并协调多个智能体，同时不让其内部指令混入你的对话记录。 |
| 70 | - **扩展你已有的智能体。** 连接 MCP 服务器和技能、配置钩子，并将智能体角色作为可读文件保存在项目或个人设置中。 |
| 71 | |
| 72 | 在 TUI 中运行 `/help` 可查看命令和键盘快捷键。 |
| 73 | |
| 74 | ## 安全 |
| 75 | |
| 76 | Codewhale 在你的机器上运行，并仅拥有你授予的访问权限。审批模式和仓库规则会限制智能体的行为；在支持的平台上，可选的操作系统沙箱可提供更强的执行边界。未知的模型价格会保持显示为未知，而不会被误报为免费。 |
| 77 | |
| 78 | 阅读[授权顺序](docs/AUTHORIZATION_ORDER.md)了解确切的策略层级，阅读[配置](docs/CONFIGURATION.md)了解本地设置。 |
| 79 | |
| 80 | ## 文档 |
| 81 | |
| 82 | - [提供商和本地模型](docs/PROVIDERS.md) |
| 83 | - [智能体团队](docs/FLEET.md) |
| 84 | - [MCP](docs/MCP.md)、[钩子](docs/HOOKS.md)和[配置](docs/CONFIGURATION.md) |
| 85 | - [本地 Web 客户端](docs/WEB.md) |
| 86 | - [全部文档](docs) |
| 87 | - [仓库结构与贡献指南](CONTRIBUTING.md#project-structure) |
| 88 | |
| 89 | ## 加入社区 |
| 90 | |
| 91 | **欢迎提交错误报告、功能建议和 pull request**，无论你已使用 Codewhale 数月，还是刚刚开始尝试。如果缺少某个提供商、工作流体验不佳，或终端界面妨碍了你，请[提交 issue](https://github.com/Hmbown/CodeWhale/issues/new/choose) 或[提交 pull request](CONTRIBUTING.md)，一起改进。我们欢迎首次贡献，贡献者也会保留已合入工作的署名。 |
| 92 | |
| 93 | 加入 [Discord](https://discord.gg/37gfS3ksug)，或在微信添加 Hunter（`hunterbown`）并申请加入 Whale Brothers 群。 |
| 94 | |
| 95 | ## 项目历史 |
| 96 | |
| 97 | Codewhale 起初名为 `deepseek-tui`，至今仍保留与其配置和会话的兼容性。如今它已不偏向任何提供商，由社区独立维护，也不隶属于任何模型提供商。 |
| 98 | |
| 99 | 感谢每一位贡献者，以及帮助项目成长的开源社区。请参阅[贡献者记录](docs/CONTRIBUTORS.md)。 |
| 100 | |
| 101 | ## 许可证 |
| 102 | |
| 103 | [MIT](LICENSE)。从其他开源项目改编的部分记录在[第三方声明](docs/THIRD_PARTY_NOTICES.md)中。 |
| 104 |