> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cascade（旧版）

> Devin Desktop 中旧版 Cascade 智能体的参考文档，涵盖模式、记忆与规则、技能、AGENTS.md、工作流程、工作树、MCP 和钩子。

> [!NOTE]
>
> Cascade 是 Devin Desktop 中的旧版智能体。Devin Desktop 已不再创建新的 Cascade 对话，也无法再打开旧的 Cascade 对话。新对话将通过 [Devin Local](https://docs.devin.ai/zh/desktop/devin-local/overview.md) 发起。

## 概述

Devin Desktop 的 Cascade 将人与 AI 之间的协作提升到了全新的高度。

在 [Devin Local](https://docs.devin.ai/zh/desktop/devin-local/overview.md) 推出之前，Cascade 是 Devin Desktop 中的本地智能体。智能体选择器中已不再提供 Cascade。

> [!NOTE]
>
> 当 workspace 以受限模式打开时，Devin Local 及其他所有 ACP 智能体均不可用。

##### 功能快速链接

> [card] [终端](https://docs.devin.ai/zh/desktop/terminal.md)
>
> 全面升级的终端体验。

> [card] [工作流程](https://docs.devin.ai/zh/desktop/cascade.md#workflows)
>
> 将重复性的执行轨迹自动化。

### 模型选择

在 Cascade 对话输入框下方的选择菜单中选择所需的模型。点击下方链接，查看所有可用模型的完整列表，以及各模型在不同套餐和定价下的可用情况。

> [card] [模型](https://docs.devin.ai/zh/desktop/models.md)
>
> Devin Desktop 中的模型可用性。

### Cascade 代码 / Cascade 聊天

Cascade 提供两种主要模式：**代码**和**聊天**。

在代码模式下，Cascade 可以创建和修改您的代码库；聊天模式则专为解答与您的代码库或通用编程原则相关的问题而优化。

在聊天模式下，Cascade 可能会向你提供新的代码建议，你可以选择接受并将其插入。

### 计划与待办事项列表

Cascade 内置规划能力，可在处理较长任务时提升表现。

在后台，一个专门的规划智能体会持续完善长期计划，而您选择的模型则专注于依据该计划执行短期操作。

Cascade 会在对话中创建待办事项列表，用于跟踪复杂任务的进度。如需更改计划，只需让 Cascade 更新待办事项列表即可。

在对话过程中，Cascade 获取到新信息 (例如 Memory) 时，也可能会自动更新计划。

### 排队消息

在等待 Cascade 完成当前任务时，你可以将新消息加入队列，待该任务完成后按顺序执行。

如需将消息添加到队列，只需在 Cascade 正在工作时输入消息并按 `Enter` 键。

* **立即发送**：在空文本框中再次按 Enter 键即可立即发送。
* **删除**：在消息发送前将其从队列中移除

### 工具调用

Cascade 可以使用多种工具，例如 Search、Analyze、MCP 以及[终端](https://docs.devin.ai/zh/desktop/terminal.md)。

它能够识别你正在使用哪些软件包和工具、哪些还需要安装，甚至可以替你完成安装。只需询问 Cascade 如何运行你的项目，然后点击 Accept 即可。

> [!NOTE]
>
> 默认情况下，Cascade 每个提示最多可进行 40 次调用。如果执行轨迹因达到此上限而停止，只需点击 `continue` 按钮，Cascade 便会从中断处恢复。但由于工具调用会产生成本，每次 `continue` 都会计为一个新的提示积分。

你可以开启 `Auto-Continue` 设置，让 Cascade 在达到调用上限时自动继续响应，而不是停止。此操作将按你所使用的模型消耗相应数量的提示积分。

在 `settings.json` 中，对应的是 `devin.autoContinue` 设置：设为 `0` 或负值即开启自动继续，Cascade 将无限期继续；设为正值 (默认为 `40`) 即关闭自动继续，Cascade 会在达到调用上限时停止，并提示你继续。

<video autoPlay muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/auto-continue.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=c18ea30e4a046e686ec73bd968fd5708" />

### 语音输入

借助语音输入，你可以通过语音与 Cascade 交互。目前，该功能可将你的语音转录为文本。

<video autoPlay controls muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/voice-mode.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=99e3fdda91ed54226237e7d4714d55e4" />

### 命名检查点与还原

你可以还原 Cascade 所做的更改。只需将鼠标悬停在原始提示上，点击右侧的还原箭头即可；也可以直接从目录中进行还原。此操作会将所有代码修改还原到你的代码库在所选步骤时的状态。

> [!WARNING]
>
> 还原操作目前不可撤销，请谨慎操作！

<video autoPlay controls muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/cascade-revert.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=2c8998de7ae41d52f7e201968b7d0fa2" />

你还可以在对话中为项目的当前状态创建命名快照/检查点，之后可随时跳转到该检查点并进行还原。

<video autoPlay controls muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/namedcheckpoints.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=f781fe8b456ecf92dc7da510409f21ca" />

### 实时感知

Devin Desktop 和 Cascade 的一项独特能力是能够实时感知你的操作，因此你无需在提示中补充先前操作的上下文。

只需告诉 Cascade“继续”即可。

<video autoPlay controls muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf-continue.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=3d31ba9067a3d44e8316e6f5adf1d875" />

### 将问题发送给智能体

如果代码中存在问题并显示在编辑器底部的“Problems”面板中，可以将这些问题作为上下文发送给智能体：

* 点击“Problems”面板顶部的 `Send all to agent`，发送当前列出的所有问题。
* 点击“Problems”面板中某个文件旁的 `Send to agent`，仅发送该文件中的问题。

### 解释并修复

在编辑器中遇到任何错误时，只需选中该错误并点击 `Explain and Fix`，Cascade 即可为你修复。

![](https://mintcdn.com/cognitionai/WE51TvKjsiyk1ZHl/desktop/assets/windsurf/windsurf-explain-fix.png?fit=max\&auto=format\&n=WE51TvKjsiyk1ZHl\&q=85\&s=320ae91d95495409e321f49e98639ffe)

### 忽略文件

如果你希望 Cascade 忽略某些文件，可以将这些文件添加到您的 workspace 根目录下的 `.devinignore` (或旧版的 `.codeiumignore`) 中。这样，Cascade 将无法查看或编辑指定路径中的文件，也无法在其中创建文件。你可以按照与 `.gitignore` 类似的格式声明文件路径。详情请参阅[忽略文件](https://docs.devin.ai/zh/desktop/context-awareness/devin-ignore.md)。

#### 全局 .codeiumignore

对于管理多个代码仓库的 Enterprise 客户，你可以在 `~/.codeium/` 文件夹中放置一个全局 `.codeiumignore` 文件，从而对所有仓库强制执行忽略规则。该全局配置适用于你系统上的所有 Devin Desktop 工作区，并与各代码仓库自身的 `.codeiumignore` 文件叠加生效。

### 代码检查工具集成

Cascade 可以自动修复生成代码中的 lint 错误。此功能默认开启，如需禁用，可点击工具调用上的 `Auto-fix`，然后点击 `disable`。此类编辑不会消耗任何积分。

![](https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/auto-fix-lint.png?fit=max\&auto=format\&n=hxeMffzXgF_RWx-U\&q=85\&s=d173740b98731de1d1570e55a47decf5)

如果 Cascade 进行某次编辑的主要目的是修复由其自身引入并自动检测到的 lint 问题，
则该次编辑可能会免收积分。这是考虑到
修复 lint 错误会增加 Cascade 的工具调用次数。

### 分享您的对话

Cascade 对话的分享链接已失效。Devin Desktop 已移除 Cascade 对话分享页面。

### @ 提及以往的对话

你还可以在其他对话中通过 `@-mention` 引用以往的对话。

这样做时，Cascade 会获取最相关、最有用的信息，例如对话摘要和检查点，以及你查询的对话中的具体内容。为避免占满上下文窗口，它通常不会获取完整的对话。

<video autoPlay controls muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/at-mention-convos.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=bad3d0cd293fdaad8a6f9f4c84589f84" />

### 同时运行多个 Cascade

用户可以同时运行多个 Cascade。你可以通过 Cascade 面板左上角的下拉菜单在它们之间切换。

> [!WARNING]
>
> 如果两个 Cascade 同时编辑同一个文件，编辑操作可能会产生竞争，导致第二次编辑有时会失败。

如果你预计两个 Cascade 会编辑相近的文件，建议使用[工作树](https://docs.devin.ai/zh/desktop/cascade.md#worktrees)将它们彼此隔离。

## 工作流程

工作流程允许用户定义一系列步骤，引导 Cascade 完成一组重复性的任务，例如部署服务或回复 PR 评论。

工作流程以 Markdown 文件的形式保存，让用户及其团队能够以简便、可重复的方式运行关键流程。

保存后，即可在 Cascade 中通过 `/[name-of-workflow]` 格式的斜杠命令调用工作流程。

> [!NOTE]
>
> 工作流程**仅支持手动调用**——Cascade 绝不会自动调用工作流程。如果你希望 Cascade 自行选用某个步骤，请改用[技能](https://docs.devin.ai/zh/desktop/devin-local/customizations.md#skills)。

工作流程是 Cascade 特有的功能，[Devin Local](https://docs.devin.ai/zh/desktop/devin-local/overview.md) 不支持工作流程。请将你的工作流程迁移为[技能](https://docs.devin.ai/zh/desktop/devin-local/customizations.md#skills)。

### 工作原理

规则通常在提示层面提供持久、可复用的上下文，从而为大语言模型提供指导。

工作流程在此基础上更进一步，在执行轨迹层面提供结构化的步骤或提示序列，引导模型完成一系列相互关联的任务或操作。

![](https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/use-workflow-pr.png?fit=max\&auto=format\&n=hxeMffzXgF_RWx-U\&q=85\&s=92b4125d6d17f2a25ffea890592331fc)

要执行某个工作流程，用户只需在 Cascade 中使用 `/[workflow-name]` 命令调用即可。

> [!TIP]
>
> 你可以在一个工作流程中调用其他工作流程！\
> \
> 例如，/workflow-1 可以包含“Call /workflow-2”和“Call /workflow-3”这样的指示。

调用后，Cascade 会依次处理工作流程中定义的每个步骤，并按要求执行操作或生成响应。

### 如何创建工作流程

要开始使用工作流程，请点击 Cascade 右上角侧滑菜单中的 `Customizations` 图标，然后进入 `Workflows` 面板。在此处点击 `+ Global` 或 `+ Workspace` 按钮，即可分别在全局级别或 workspace 级别创建新的工作流程。

工作流程以 Markdown 文件的形式保存在 `.devin/workflows/` 目录 (或旧版的 `.windsurf/workflows/` 目录) 中，包含标题、描述以及一系列步骤，每个步骤都附有供 Cascade 遵循的具体指示。

### 工作流程自动发现

Devin Desktop 会自动从多个位置发现工作流程，让您可以灵活地组织它们：

* **当前 workspace 及其子目录**：您当前 workspace 及其子目录中的所有 `.devin/workflows/` (以及旧版 `.windsurf/workflows/`) 目录
* **Git 代码仓库结构**：对于 git 仓库，Devin Desktop 还会向上搜索至 git 根目录，查找上级目录中的工作流程
* **多文件夹 workspace 支持**：当同一 workspace 中打开了多个文件夹时，工作流程会自动去重，并以最短的相对路径显示

#### 工作流程存储位置

| 作用域 | 位置 | 说明 |
| - | - | - |
| Workspace | `.devin/workflows/*.md` (首选) 或 `.windsurf/workflows/*.md` (回退) | 位于当前 workspace、其任意子目录，或向上直至 git 根目录的任意父目录中。随代码仓库一起提交。 |
| 全局 | `~/.codeium/windsurf/global_workflows/*.md` | 在本机的所有 workspace 中均可用。不提交。 |
| 内置 | 由 Devin Desktop 管理 | Devin Desktop 自带的模板 (例如 `/plan`) 。 |
| [系统 (企业) ](#system-level-workflows-enterprise) | 因操作系统而异 (例如 `/etc/devin/workflows/`，旧版为 `/etc/windsurf/workflows/`) | 由 IT 部署，终端用户只读。 |

通过用户界面新建的工作流程会保存在当前 workspace 的 `.devin/workflows/` 目录中，而不一定位于 git 根目录。如果某个 workspace 仍包含 `.windsurf/` 目录且您拒绝了迁移，则会改为保存在 `.windsurf/workflows/` 中。如需创建全局工作流程，请使用工作流面板中的 `+ Global` 按钮，或直接在 `~/.codeium/windsurf/global_workflows/` 中创建文件。

每个工作流程文件最多 12000 个字符。

<video autoPlay controls muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/create-workflow.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=b0f3d54a0d24966384a91042468f72bf" />

#### 使用 Cascade 生成工作流程

你也可以让 Cascade 为你生成工作流程！如果工作流程需要在某个 CLI 工具中执行一系列步骤，这种方式尤其好用。

<video autoPlay controls muted loop playsInline src="https://mintcdn.com/cognitionai/hxeMffzXgF_RWx-U/desktop/assets/windsurf/cascade/create-workflow-with-cascade.mp4?fit=max&auto=format&n=hxeMffzXgF_RWx-U&q=85&s=f14c9012ab0e92d631b808072c439f60" />

### 示例工作流程

工作流程的用例非常丰富，例如：

> [card] /address-pr-comments
>
> 这是我们团队内部用于处理 PR 评论的一个工作流程：
>
> ```
> 1. Check out the PR branch: `gh pr checkout [id]`
>
> 2. Get comments on PR
>
>  bash
>  gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line, original_line, created_at, in_reply_to_id, pull_request_review_id, commit_id}'
>
> 3. For EACH comment, do the following. Remember to address one comment at a time.
>  a. Print out the following: "(index). From [user] on [file]:[lines] — [body]"
>  b. Analyze the file and the line range.
>  c. If you don't understand the comment, do not make a change. Just ask me for clarification, or to implement it myself.
>  d. If you think you can make the change, make the change BEFORE moving onto the next comment.
>
> 4. After all comments are processed, summarize what you did, and which comments need the USER's attention.
> ```

> [card] /git-workflows
>
> 使用相应的 CLI 命令，按预定义格式提交 commit，并创建标题和描述规范统一的拉取请求。

> [card] /dependency-management
>
> 根据配置文件 (例如 requirements.txt、package.json) 自动安装或更新项目依赖。

> [card] /code-formatting
>
> 在保存文件时或 commit 之前，自动运行代码格式化工具 (如 Prettier、Black) 和 lint 工具 (如 ESLint、Flake8) ，保持代码风格一致并及早发现错误。

> [card] /run-tests-and-fix
>
> 运行或添加单元测试、端到端测试并自动修复错误，在 commit、合并或部署之前保障代码质量。

> [card] /deployment
>
> 自动执行将您的应用部署到各个环境 (开发环境、预生产环境、生产环境) 的步骤，包括必要的部署前检查和部署后验证。

> [card] /security-scan
>
> 将安全漏洞扫描集成到 CI/CD 流水线中，或按需对您的代码库触发扫描。

### 系统级工作流 (企业版)

企业组织可以部署系统级工作流。这类工作流在所有工作区中全局可用，没有管理员权限的终端用户无法修改。它非常适合用于统一推行组织级的开发流程、部署步骤和合规工作流程。

系统级工作流从各操作系统对应的目录中加载。如果 `Devin` 工作流目录存在，Devin Desktop 会加载该目录；仅当该目录不存在时，才会回退到旧版 `Windsurf` 工作流目录。两个目录的内容不会合并，因此创建 `Devin` 目录时，请将所有旧版工作流移入其中：

**macOS：**

```
/Library/Application Support/Devin/workflows/*.md
/Library/Application Support/Windsurf/workflows/*.md   # 旧版回退路径
```

**Linux/WSL：**

```
/etc/devin/workflows/*.md
/etc/windsurf/workflows/*.md   # 旧版回退路径
```

**Windows：**

```
C:\ProgramData\Devin\workflows\*.md
C:\ProgramData\Windsurf\workflows\*.md   # 旧版回退路径
```

将您的工作流程文件(`.md` 格式)放入与您的操作系统对应的目录中。系统会自动加载这些目录下的所有 `.md` 文件。

#### 工作流程优先级

当多个级别中存在同名工作流程时，系统级工作流的优先级最高：

1. **系统** (最高优先级) - 由 IT 部署的组织级工作流程
2. **Workspace** - 位于 `.devin/workflows/` (或旧版 `.windsurf/workflows/`) 中的项目专属工作流程
3. **全局** - 位于 `~/.codeium/windsurf/global_workflows/` 中的用户自定义工作流程
4. **内置** - Devin Desktop 提供的默认工作流程

也就是说，如果组织部署了某个特定名称的系统级工作流，它将覆盖所有同名的 workspace、全局或内置工作流程。

在 Devin Desktop 用户界面中，系统级工作流会带有“系统”标签，且终端用户无法删除。

> [!NOTE]
>
> **重要**：系统级工作流应由您的 IT 或安全团队管理。请确保内部团队按照您组织的策略负责部署、更新和合规事宜。您可以借助移动设备管理 (MDM) 或配置管理等标准工具和工作流程来完成这些工作。

## 工作树

Devin Desktop 支持使用 git 工作树并行运行 Cascade 任务，且不会干扰您的主 workspace。

使用工作树时，每个 Cascade 对话都拥有独立的会话，Cascade 可以在其中编辑代码、构建和测试，而不会干扰您的主 workspace。

[Devin Local](https://docs.devin.ai/zh/desktop/devin-local/worktrees.md) 还可以在现有 worktree 中启动会话 (通过智能体位置选择器选取) ，并通过 **Merge** 按钮将更改合并回来。

### worktree 基本用法

开始使用工作树最简单的方法，是在 Cascade 输入框右下角切换到“Worktree”模式。

![](https://mintcdn.com/cognitionai/WE51TvKjsiyk1ZHl/desktop/assets/windsurf/worktree-toggle.png?fit=max\&auto=format\&n=WE51TvKjsiyk1ZHl\&q=85\&s=c360271ef16d55e236aa5a0c3f4844f6)

> [!NOTE]
>
> 目前，你只能在 Cascade 会话开始时切换到 worktree。对话一旦开始，就无法再移至其他 worktree。

Cascade 在 worktree 中完成文件更改后，你可以点击“merge”，将这些更改合并回你的主 workspace。

![](https://mintcdn.com/cognitionai/WE51TvKjsiyk1ZHl/desktop/assets/windsurf/worktree-merge.png?fit=max\&auto=format\&n=WE51TvKjsiyk1ZHl\&q=85\&s=574816f7a9d6a1b49b6d931c2ede8051)

### 位置

工作树按代码仓库名称分类存放在 `~/.windsurf/worktrees/<repo_name>` 下。

每个 worktree 都会分配一个唯一的随机名称。

如需查看活跃工作树列表，可在代码仓库目录中运行 `git worktree list`。

> [!WARNING]
>
> 由于工作树与原始项目位于不同目录，**依赖相对路径的构建系统或工具** (例如 `../shared-lib` 引用、通过符号链接引入的依赖，或按路径解析的单体仓库源码依赖) 在 worktree 中可能无法正常工作。如果您的项目使用了指向代码仓库根目录之外的相对路径，请配置 [`post_setup_worktree` 钩子](https://docs.devin.ai/zh/desktop/cascade#setup-hook)，用于创建所需的符号链接，或将所需文件复制到预期位置。

### 初始化钩子

每个 worktree 都包含您的代码仓库文件的副本，但不包含 `.env` 文件或其他未纳入版本控制 (version-controlled) 的软件包。

如果你希望在每个 worktree 中包含额外的文件或软件包，可以使用 `post_setup_worktree` 钩子将它们复制到 worktree 目录中。

`post_setup_worktree` 钩子会在每个 worktree 创建并配置完成后运行，并在新的 **worktree** 目录中执行。

`$ROOT_WORKSPACE_PATH` 环境变量指向原始 workspace 路径，可用于访问原始代码仓库中的文件，或以原始代码仓库为基准运行命令。

#### 示例

在创建新的 worktree 时，复制环境文件并安装依赖。

**配置** (位于 `.windsurf/hooks.json`) ：

```json theme={null}
{
  "hooks": {
    "post_setup_worktree": [
      {
        "command": "bash $ROOT_WORKSPACE_PATH/hooks/setup_worktree.sh",
        "show_output": true
      }
    ]
  }
}
```

**脚本** (`hooks/setup_worktree.sh`):

```bash theme={null}
#!/bin/bash

# 从原始工作区复制环境文件
if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env" .env
    echo "Copied .env file"
fi

if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
    echo "Copied .env.local file"
fi

# 安装依赖
if [ -f "package.json" ]; then
    npm install
    echo "Installed npm dependencies"
fi

exit 0
```

此钩子可确保每个工作树都会自动完成所需的环境配置并安装依赖。

### 清理

为避免占用过多磁盘空间，Devin Desktop 会在创建新的 worktree 时自动清理较旧的工作树。每个 workspace 最多可包含 **20** 个工作树。

工作树按上次访问时间进行清理，最久未访问的会最先被删除。清理以 workspace 为单位分别进行，确保不同仓库的工作树彼此独立、互不影响。

此外，如果你手动删除某个 Cascade 对话，Devin Desktop 会自动删除与之关联的 worktree。

### 源代码管理面板

默认情况下，Devin Desktop 不会在 SCM 面板中显示由 Cascade 创建的工作树。
如需更改此行为，可在设置中将 `git.showDevinWorktrees` 设为 `true`，即可在 SCM 面板中显示这些工作树。

> [!NOTE]
>
> 旧的 `git.showWindsurfWorktrees` 设置已弃用。在未设置 `git.showDevinWorktrees` 的情况下，现有配置中的该设置仍会生效，但今后请改用 `git.showDevinWorktrees`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.