# 动态工作流

用于 GitHub Copilot 协调复杂任务的工作，可能结合确定性操作、代理、工具、API 调用和用户交互。

> \[!NOTE] 此功能处于 公开预览 阶段，并且可能会发生变化。

本文介绍动态工作流及其用途。 有关使用方法的详细信息，请参阅 [使用动态工作流](/zh/copilot/how-tos/use-copilot-agents/use-dynamic-workflows)。

## 关于动态工作流

动态工作流是一个定义任务执行方式的程序。它可以将自动化步骤与一个或多个代理的工作相结合。 步骤可以依次运行、并行运行，或混合这两种方式运行。

动态工作流尤其适用于复杂的多步骤任务，以及那些需要反复执行、且每次都按一组确定性操作来完成的任务。 例如，可以使用动态工作流来调查服务中断事件，方法是收集日志和遥测数据、分配独立代理来分析不同的系统，并将其结构化结果合并到时间线和根本原因报告中。

动态工作流可以：

* 运行命令、使用工具或调用其他服务。
* 将目标划分为任务，并并行运行独立任务。
* 将结果从一个阶段传递到下一个阶段。
* 让子代理验证彼此的发现。
* 将结果合并为单个答案。
* 询问你是否正在使用的应用程序支持输入。
* 在检查点处暂停，以便您在准备好后查看结果，并在就绪时继续运行。

一切都在代码中定义：步骤、何时涉及代理以及如何使用其结果。 智能体负责处理需要分析或判断的部分。

工作流可以要求代理以指定格式返回结果，以便后续步骤可以使用它们。
Copilot 如果需要，可以要求代理更正格式。

动态工作流在扩展中 Copilot 定义。 它们可以是：

* **由 Copilot 撰写。** 描述你希望工作流遵循的任务和流程。
* **由你撰写。** 您可以使用Copilot的内置编写指南自行编写扩展。
* **与你共享。** 扩展加载后，即可使用其动态工作流。

若要使用动态工作流，可以要求 Copilot 使用自然语言按名称运行它。 例如：

```copilot copy
Run the java-security-review dynamic workflow on the java files in the current directory.
```

从提示启动动态工作流时， Copilot 在后台运行该工作流，并在完成后报告回来。 可以在会话中继续运行。

> \[!IMPORTANT]
> 聊天代理仅在显式请求时创建或运行动态工作流，或者当技能或斜杠命令指示它执行此操作时。

在 Copilot CLI 中，还可以使用 `copilot workflow run WORKFLOW-NAME` 直接从终端运行现有的动态工作流。 您无需打开交互式聊天，也无需让客服人员发起。 工作流仍可使用代理执行各个步骤。

该命令等待运行完成或停止，然后再将控件返回到 shell。 使用这种方法可使用特定输入重复运行工作流、保存其结果，或通过脚本或 CI/CD 管道运行该工作流。 有关详细信息，请参阅“[使用动态工作流](/zh/copilot/how-tos/use-copilot-agents/use-dynamic-workflows#running-a-dynamic-workflow-from-the-command-line)”。

还可以通过扩展的斜杠命令、自定义工具或以编程方式调用的钩子，或者从使用该 GitHub Copilot SDK 函数的其他代码启动工作流。 在 Copilot app 中，某个扩展可以提供一个画布（即自定义界面），其中包含用于启动工作流的控件。 这些替代方法取决于扩展和正在使用的客户端。

有关画布的更多信息，请参阅 [在 GitHub Copilot 应用中使用画布扩展](/zh/copilot/how-tos/github-copilot-app/working-with-canvas-extensions)。

要查看有哪些动态工作流可用，只需询问 Copilot：

```copilot copy
What dynamic workflows are available?
```

## 动态工作流与 Autopilot 和 Fleet 有何不同

如果已使用 autopilot 模式和 `/fleet` 命令，动态工作流可能看起来是类似的东西。 主要区别在于如何规划和控制工作，而不仅仅是使用多少个代理。

* **Autopilot** 是一种强调自主性的模式。 它允许 Copilot 在无需在每个步骤后暂停以获取你的输入的情况下继续完成任务。
* **`/fleet`** 鼓励 Copilot 将工作委托给子代理并并行协调其工作。 Copilot 决定每次如何分解任务。
* **动态工作流** 执行代码中定义的流程。 工作流的作者定义步骤、条件和交接。 此过程可以使用一个代理或多个代理，工作可按顺序进行、并行进行，或两者结合进行。

重用工作流意味着重用其步骤和规则。 这些步骤的执行路径会随着输入或发现结果而变化，代理在不同次运行中也可能给出不同的答案。

| 方面                  | Autopilot          | Fleet                | 动态工作流                       |
| ------------------- | ------------------ | -------------------- | --------------------------- |
| 主要用途                | 让 Copilot 继续自主运行   | 鼓励 Copilot 将工作委托给子代理 | 执行代码中定义的过程                  |
| 谁定义该过程？             |                    |                      |                             |
| Copilot 决定后续步骤      |                    |                      |                             |
| Copilot 决定如何划分和协调工作 | 工作流作者定义步骤、条件和移交    |                      |                             |
| 工作方式                | 取决于任务和 Copilot 的决策 | 独立工作项可并行委派           | 顺序执行、并行执行，或两者结合，使用单个代理或多个代理 |

有关管理工作流运行的详细信息，请参阅 [限制动态工作流](#limiting-a-dynamic-workflow) 和 [查看、停止、暂停和恢复运行](#watching-stopping-pausing-and-resuming-runs)。

## 何时使用动态工作流

如果要定义可以重复使用的进程，或者单个任务需要明确的阶段、检查或限制，请使用动态工作流。 合适的候选项包括：

* 运行发布检查，要求一个代理评估失败，并暂停检查结果，然后再恢复。
* 同时查看拉取请求中的多个已更改的文件。
* 使用代码查找合并拉取请求的未解析审阅注释，然后询问两个模型注释是否仍然重要。 仅当两者都同意时，工作流的代码才会报告调查结果。
* 一次性跨多个目录在大型代码库中查找某种模式，例如缺少要删除的 API 的测试或用法。
* 研究更改，根据调查结果规划其实施，然后进行更改。
* 启动一次耗时较长且可能成本高昂的运行，后续你可能需要暂停并恢复它。

如果只是想快速获得答案或进行简单修改，那么在标准聊天模式下使用常规提示词通常就足够了。

## 动态工作流权限

动态工作流的子代理使用 CLI 的权限系统，并继承启动它们的会话的权限授予。 会话中已允许的任何内容都适用于动态工作流的子代理。

如果某个工作流的子代理尝试执行尚未获准的操作，则请求会在交互式 CLI 会话中显示为正常权限提示。 你可以按照主代理的相同方式批准它。 需要权限的子代理只需等待，直到你作出响应。

如果一个子代理请求某项权限，并且你在会话期间授予该权限，该授权适用于所有需要相同权限的子代理。

使用 `copilot workflow run`时，该命令不显示权限审批提示。 在启动运行之前，授予工作流代理所需的权限。 请参阅“[使用动态工作流](/zh/copilot/how-tos/use-copilot-agents/use-dynamic-workflows#running-a-dynamic-workflow-from-the-command-line)”。

扩展还可以直接在这些权限提示之外运行自己的代码。

## 创建动态工作流

您可以在交互式会话中让 Copilot 创建动态工作流。 告知 Copilot 希望工作流完成的操作。

默认情况下，Copilot 会为当前会话创建一个扩展。 你可以改为要求它创建个人或项目扩展，或使用 Copilot的内置创作指南自行编写扩展。

有关详细信息，请参阅“[使用动态工作流](/zh/copilot/how-tos/use-copilot-agents/use-dynamic-workflows)”。

## 修改动态工作流

通常，首次使用动态工作流时，会通过运行具有有限作用域的动态工作流来测试它。 例如，对于一个用于处理多个文件的动态工作流，一开始你可以先让 Copilot 仅对两三个文件运行该工作流。 然后，您可以评估结果。 如有必要，您可以先让 Copilot 修改工作流，然后再运行一次。

使用自然语言请求来 Copilot 修改工作流的已保存定义，而不是仅针对单次运行覆盖某个限制。 例如：

```copilot copy
Update the check-python-style dynamic workflow to use no more than 10 subagents in total.
```

修订将保存到动态工作流的扩展中，无论该扩展是按会话保存、保存在个人扩展目录中，还是保存在项目存储库中。 加载更新后的扩展后，后续运行将使用修订版。 这不会替换暂停运行中保存的结果。

如果修改在项目存储库中共享的动态工作流，则处理该项目的人员必须拉取存储库的更新版本，然后重新加载其扩展，然后才能使用修订的版本。

## 复用和共享动态工作流

默认情况下，Copilot 为你创建的工作流仅限于当前会话。 可以将扩展复制到个人扩展目录中，以便跨会话使用扩展，也可以复制到存储库的扩展目录中，以便与处理该项目的人员共享该扩展。 这会共享定义，而不是原始会话的运行历史记录或保存的进度。 有关详细信息，请参阅“[使用动态工作流](/zh/copilot/how-tos/use-copilot-agents/use-dynamic-workflows#reusing-and-sharing-dynamic-workflows)”。

若要更广泛地共享动态工作流，可以将动态工作流打包为插件，并通过首选的插件管理系统分发它。 有关详细信息，请参阅“[为 GitHub Copilot CLI 创建插件](/zh/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating)”。

## 限制动态工作流

您可以为动态工作流设置以下限制：

* 可同时处于活动状态的工作流拥有代理的最大数目。
* 在一次运行期间，由工作流拥有的代理累计可启动的最大数量。
* 最长的活动运行时间，包括暂停前使用的时间。 运行暂停期间的时间不计入。
* 工作流的代理及其子代理可以使用的大致最大数目 AI credits 。

  > \[!NOTE]
  > Copilot 跟踪工作流代理使用的信用额度，并在总工数达到限制时停止新工作。 使用情况在发生后报告，因此正在进行的工作可能需要超过限制的总数。 这是近似最大值，而不是硬上限。

可以在三个位置定义限制：

* **在提示中：** 在用于运行动态工作流的提示中，用自然语言说明限制条件。 例如：

  ```copilot
  Use the architecture-research dynamic workflow on this repo, with a timeout of 1 hour.
  ```

* **在工作流代码中：** 创建动态工作流时，你可以（可选地）定义在动态工作流运行时应使用的限制条件。

* **在个人设置中：** 您可以为 Copilot 定义默认限制。 如果提示或工作流代码中未指定同类型的限制，这些限制将适用于你运行的任何动态工作流。

  在 Copilot CLI 命令中，可以使用以下命令 `/settings` 配置动态工作流的个人默认限制。

  * `workflows.defaultLimits.maxConcurrentSubagents`
  * `workflows.defaultLimits.maxTotalSubagents`
  * `workflows.defaultLimits.timeoutSeconds`（必须以秒为单位指定）
  * `workflows.defaultLimits.maxAiCredits`

  例如：

  ```copilot
  /settings workflows.defaultLimits.timeoutSeconds 3600
  ```

这些限制按上述所示的顺序排列优先级。 如果在提示中指定限制，则会覆盖动态工作流或个人设置中定义的任何相应限制。

并发子代理数量限制会使额外的子代理等待，直到其他子代理完成。 到达它不会停止工作流。

其他限制可以停止运行，但其状态和保存的结果会保留，以便稍后可以恢复它。 恢复以限制停止的运行时，请增加该限制以允许更多工作。 新限制是运行的总限制，包括停止前的使用情况，而不是新的津贴。

### 防止意外使用 AI credit

启动多个子代理的工作流可能需要很长时间才能完成，并消耗大量 AI credits。

为防止 AI credits 意外消耗过高，在将动态工作流用于大规模作业之前，应先在小范围内进行测试。 执行小型运行后，请检查实际 AI credit 使用情况，然后为大规模运行设置适当的限制 AI credits 。

## 监视、停止、暂停和恢复运行

你可以在Copilot CLI会话中使用`/workflows`斜杠命令，或在\*\*\*\* 中点击Copilot app按钮，以查看当前或过去的工作流运行记录。

详细信息会显示 AI credits 的使用情况，以及工作流报告的所有阶段、进度信息和子代理。 可以从此处取消或暂停当前运行中的工作流。 扩展还可以提供自己的进度视图，例如在画布中 Copilot app。

如果某次运行已被暂停，或者因达到某个限制而停止，你可以在运行列表中选择该运行并继续执行。 工作流可以重复使用已完成的步骤和子代理中保存的结果。 未保存的内容可能需要重新运行。

有关详细信息，请参阅“[使用动态工作流](/zh/copilot/how-tos/use-copilot-agents/use-dynamic-workflows#monitoring-and-managing-dynamic-workflow-runs)”。