Capri 教程：使用 Windows AI 代理控制文件、项目和代码

什么是 Capri？

Capri 是一款开源的赛博朋克风格 Windows AI 智能体。它提供原生桌面界面，让你通过 AI 助手处理文件、项目文件夹、代码、Shell 工具、应用程序和网页。你无需编写终端命令，只需用自然语言描述目标，Capri 就会协调完成相关工作。

Capri 负责界面和工具层，而外部助手提供 AI 推理能力。它开箱即支持 Claude Code、Codex 和 Antigravity。其他助手也可以通过自定义适配器连接。

Capri 是一个独立的非官方粉丝项目，灵感来自赛博朋克题材和《赛博朋克：边缘行者》。它与 CD PROJEKT RED、Netflix、Studio Trigger、Anthropic、OpenAI 或 Google 没有任何关联，也未获其认可。

主要功能

• 多种 AI 引擎：连接 Claude Code、Codex、Antigravity，或通过自定义适配器连接其他助手。
• 原生 Windows 界面：使用已安装的桌面应用，无需直接在终端中操作。
• 文件和项目工具：查找、读取、整理和编辑文件或完整的项目文件夹。
• 智能体工作流：Capri 可以规划任务、请求使用工具、检查结果并报告执行情况。
• 代码辅助：让所选引擎编写、重构、调试和运行代码。
• 审批控制：在 Capri 修改系统前，检查敏感操作并批准或拒绝。
• 可配置范围：将访问限制在选定文件夹内，并选择询问、自动或只读权限模式。

系统要求

Capri 目前要求使用 Windows 10 或更高版本。它以 Windows .exe 安装程序的形式发布。macOS 和 Linux 版本已列入项目路线图，但目前尚未推出。

你还需要自己的受支持 AI 助手账户或 API 密钥。Capri 本身基于 MIT 许可证开源，但连接的 AI 提供商可能会按照其自身定价收取使用费用。

在 Windows 上安装 Capri

1. 下载安装程序

打开最新 Capri 版本，然后下载 Capri-Setup.exe。请使用官方代码仓库的版本发布页面，不要从未知的第三方下载源获取安装程序。

2. 运行安装向导

1. 打开 Capri-Setup.exe。
2. 按照安装向导操作。
3. 安装完成后，从 Windows 开始菜单打开 Capri。

由于 Capri 是一款新应用，下载信誉可能尚未建立，Windows SmartScreen 可能会显示警告。如果你从官方版本发布页面获取了安装程序，请选择更多信息，然后选择仍要运行以继续。

3. 连接 AI 引擎

首次启动时，Capri 会要求你选择助手。选择 Claude Code、Codex、Antigravity 或其他受支持的选项，然后登录或提供所需的 API 密钥。

你的请求会由所连接的助手处理。因此，该提供商的条款、隐私政策、定价和账户规则均适用于相关处理过程。

Capri 如何处理任务

1. 你描述目标：在桌面应用中输入自然语言请求。
2. Capri 选择引擎：请求会被转发到你配置的 AI 助手。
3. 引擎制定计划：助手确定所需的步骤和工具。
4. Capri 展示敏感操作：根据你的权限设置，你可以检查请求执行的文件或系统操作。
5. 你批准或拒绝：获批准的操作会通过 Capri 的工具层执行。
6. Capri 报告结果：智能体检查执行结果并总结完成的工作。

基本使用示例

整理文件夹

要清理文件夹，请确定目标位置并描述所需的整理方式：

整理我的下载文件夹，并按文件类型将文件分组。移动任何文件前先向我展示计划。

Capri 可以扫描文件夹、提出计划，并在移动文件前请求批准。接受操作前，请仔细检查目标文件夹和文件名。

调查并修复代码

打开相关项目文件夹或授予 Capri 访问权限，然后向 Capri 提出明确的请求：

找出这个项目中的错误，解释原因，修复它，并运行可用的检查。

所选 AI 引擎可以检查代码、定位可能的问题、编辑相关文件并运行检查。为了更安全地审查变更，请让 Capri 在修改项目之前先解释拟议的更改。

总结文档

Capri 可以处理允许访问的文件夹中的多个文件。例如：

总结这个文件夹中的每个 PDF，并写入一份合并后的总结文档。

批准任务前，请确认 Capri 将读取哪个文件夹，以及计划在哪里保存生成的文档。

创建 Web 项目

你也可以请求完整的开发工作流：

在此文件夹中创建一个新的 Web 应用，安装其依赖项并启动它。

此类请求可能涉及创建文件、下载软件包、运行 Shell 命令和启动进程。批准前，请检查拟使用的框架、命令和目标目录。

配置权限和范围

README 提供了以下配置示例：

engine: claude-code

permissions:
  mode: ask
  allowed_folders:
    - ~/Documents
    - ~/Projects

interface:
  theme: cyberpunk

engine 值用于选择已连接的助手。文档中列出的值包括 claude-code、codex、antigravity 和 custom。

permissions 部分支持三种文档所述的模式：

• ask： Capri 会在执行操作前询问。这是了解代理行为时最适合的起点。
• auto： 操作可以自动执行。仅当你了解任务并严格限制了其范围时才使用此模式。
• read-only： 仅使用 Capri 进行检查和分析，不允许修改内容。

allowed_folders 列表限制代理可以访问的位置。建议授予其访问特定工作目录的权限，而不是整个驱动器或用户配置文件。

高级技巧

编写边界清晰的提示

说明目标文件夹、期望结果、验证方法，以及需要确认的操作。明确的请求可以减少歧义：

Review the project in my Projects folder. Identify the cause of the failing tests, explain your proposed edits, and wait for approval before changing files. After approval, run the existing test suite.

从只读模式开始

对于不熟悉的代码仓库或文档集合，请从 read-only 访问权限开始。让 Capri 检查相关材料并提出计划。只有在准备授权编辑时，才更改权限模式。

使用隔离的项目文件夹

将实验性工作复制到专用文件夹中，并仅授予 Capri 访问该目录的权限。这样可以限制意外更改，也便于检查产生的文件差异。

将计划与执行分开

对于大型任务，先请求计划，不进行任何修改。检查步骤后，再发出第二条指令，仅授权已批准的部分。这对于批量文件操作、依赖安装或大范围重构尤其有用。

在适当时切换引擎

Capri 允许你在受支持的 AI 引擎之间进行选择。如果你拥有多个助手的账户，请选择最适合当前任务的助手。请记住，每个提供商都有各自的功能、费用和隐私条款。

谨慎使用自定义适配器

其他助手可以通过自定义适配器集成。使用适配器时，请确认其如何处理凭据、请求、工具调用和返回的数据。README 未提供适配器实现说明，因此在构建集成前，请查阅项目当前的文档或贡献资源。

不要假定路线图中的每项功能都已提供

路线图将插件系统、语音控制、任务调度器、主题库以及 macOS 和 Linux 版本列为计划中的功能，而非已完成的功能。在围绕这些功能设计工作流前，请查看最新发布说明。

安全指南

• 检查每项敏感操作： 特别注意删除、移动、替换、Shell 命令和依赖安装。
• 限制文件夹访问： 仅开放当前任务所需的文件。
• 保留备份： 在批量整理、自动编辑或其他大型操作前，备份重要数据。
• 保护凭据： 切勿分享 API 密钥、账户令牌或其他机密信息。
• 检查生成的命令： 在允许 Capri 执行 Shell 命令前，先确认你理解该命令。
• 使用版本控制： 对于代码项目，在请求大规模编辑前提交当前状态，或以其他方式保留当前状态。

如果发现安全问题，请遵循项目的安全问题报告说明，并私下报告。

故障排除与项目资源

如果安装程序、引擎连接或代理工作流未按预期运行，请查看 Capri GitHub 仓库和最新发布说明。可以通过项目问题表单提交错误报告和功能建议。

我们欢迎在错误报告、文档、主题、功能提案和引擎适配器等方面做出贡献。提交更改前，请先查看仓库的贡献指南。

结语

Capri 为 Windows 用户提供了一个桌面界面，用于指挥受支持的 AI 助手处理文件、项目和代码。安装应用程序，连接偏好的引擎，限制其仅访问所需文件夹，然后从基于批准或只读的权限开始。在允许任何 AI 代理操作你的计算机时，清晰的提示、谨慎的检查、备份和严格的访问边界都至关重要。