使用动态工作流

在 GitHub Copilot CLI 和中 GitHub Copilot app查找、运行、监视和恢复动态工作流。

在本文中

注意

此功能处于 公开预览 阶段，并且可能会发生变化。

本文介绍如何在和 中创建、使用和共享动态工作流。

有关动态工作流及其工作原理的概述，请参阅 动态工作流。

先决条件

若要在 Copilot CLI 中使用动态工作流，必须先启用实验功能：可以通过使用带有 /experimental on 命令行选项运行 CLI，或在交互式会话中使用 --experimental 来启用。

了解可用的动态工作流

你可能已经有权访问会话中的一个或多个动态工作流，例如，通过你正在使用的存储库中的个人扩展或扩展。 如果是这样，可以通过在提示符中按名称提及它来使用其中一个。

要了解是否有任何可用的动态工作流，只需询问 Copilot。 例如：

Copilot prompt
What dynamic workflows are available?

如果动态工作流可用，可以要求 Copilot 描述一个工作流。 例如：

Copilot prompt
Tell me more about the java-security-checks dynamic workflow.

如果还没有任何动态工作流，可以创建一个。 请参阅 创建动态工作流。

运行动态工作流

  1. 在 Copilot 会话中，输入自然语言提示，让 Copilot 运行动态工作流。

    使用工作流的注册名称，并提供任何所需的输入。 例如，执行安全审查的动态工作流通常会要求你指定它应针对哪些文件运行。 在这种情况下，可能会输入如下提示：

    Copilot prompt
    Run the java-security-checks dynamic workflow on the java files in the current directory, with an AI credit limit of 500.

    重要

    对动态工作流设置限制是可选的，但建议这样做，因为这有助于控制资源使用并防止过度消耗 AI credits。 有关可以设置的限制的详细信息，请参阅 动态工作流。

  2. 根据当前的权限审批设置， Copilot 要求你在启动之前批准动态工作流运行。 选择 是。

如果扩展提供了另一种方法来启动其工作流，例如斜杠命令或画布控件 Copilot app，请按照该扩展的说明进行操作。

从命令行运行动态工作流

  1. 在终端中，使用 Copilot CLI 命令 copilot workflow run WORKFLOW-NAME [OPTIONS] 运行现有动态工作流。

    工作流必须通过个人扩展、项目扩展或已安装的插件提供。 如果在聊天会话中创建工作流，请先使其扩展在该会话之外可用。 请参阅 “重用和共享动态工作流”。

    使用 --args 以 JSON 格式为工作流提供输入。

    重要

    即使你在终端中运行权限审批，此命令也不会显示权限审批提示。 在启动前，授予工作流代理所需的权限，例如使用 --allow-tool 或 --allow-url。 无法自动批准的请求被拒绝。 有关详细信息，请参阅“GitHub Copilot 命令行界面编程参考”。

    例如，假设你有一个名为 java-security-checks 接受 directory 输入的工作流，需要读取文件的权限：

    Shell
    copilot workflow run java-security-checks \
   --args '{"directories":["java/src","java/tests"]}' \
   --allow-tool=read

    替换工作流名称、输入字段和与工作流匹配的权限。 如果工作流不需要任何输入，则省略 --args。

    或者，将 JSON 输入内容放入文件中，并在其路径前加上 @：

    Shell
    copilot workflow run java-security-checks \
   --args @workflow-input.json \
   --allow-tool=read

  2. 查看工作流报告的各个阶段和进度消息。 完成后，该命令会输出结果（如果有返回结果）并退出。 如果运行在未完成时暂停或停止，该命令会报告该运行的状态和运行 ID。 若要中断运行，请按 Ctrl+C。

工作流中已配置的限制和您的个人默认限制仍然适用。 请参阅“动态工作流”。

将结果保存到文件

添加 --result-file 以将工作流的返回值写入 JSON 文件，而不是将其打印到终端中。 进度消息仍显示。

Shell
copilot workflow run java-security-checks \
   --args @workflow-input.json \
   --result-file security-results.json \
   --allow-tool=read

该文件仅包含返回的值，而不包含进度消息或运行详细信息。 从启动命令的目录解析相对路径。

仅当工作流成功完成并返回结果时，才会写入该文件。 只有在成功写入新结果后，才会替换现有文件。 已暂停、失败或中断的运行不会更改任何现有文件。

在脚本中运行工作流

对于脚本和 CI/CD 管道，请在运行命令之前配置身份验证和权限。 可使用身份验证环境变量，例如 COPILOT_GITHUB_TOKEN。 请参阅“GitHub Copilot CLI 命令参考”。

若要在工作目录尚未受信任时加载项目扩展，请为该调用设置 GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true 。 这样，存储库扩展代码就可以运行。 仅将其用于信任的代码。 你仍必须授予工作流代理所需的工具权限。

用于 --silent 取消进度输出。 添加 --output-format json 后，即可接收一条包含工作流名称、运行 ID、状态以及返回的任何结果的 JSON 记录：

Shell
copilot --allow-tool=read workflow run java-security-checks \
   --args @workflow-input.json \
   --silent --output-format json

创建动态工作流

默认情况下， Copilot 在当前会话的扩展中创建工作流。 你也可以让它在个人扩展或项目扩展中创建该工作流。

  1. 描述希望工作流完成的内容、所需的步骤顺序、哪些部件应使用代理以及任何限制。 例如：

    Copilot prompt
    Create a dynamic workflow named review-changed that lists changed files, asks an agent to review them, and summarizes the findings.

    注意

    如果未提供工作流的名称， Copilot 请在创作过程中选择一个。

  2. 根据当前的权限审批设置，系统会要求你允许 Copilot 创作新的动态工作流。 选择 是。

Copilot 在创建和注册动态工作流时，可能会请求其他审批。

  1. 创作过程完成后，检查工作流是否已成功创建并注册。 为此，请向 Copilot 询问有哪些可用的动态工作流。

创建和注册工作流不会启动运行。 若要使用此功能，请参阅 运行动态工作流。

还可以自行编写扩展，并参考该 Copilot扩展。 要阅读内置指南，请输入：

Copilot prompt
Show me the guidance for writing dynamic workflows.

复用和共享动态工作流

动态工作流作为 Copilot 扩展实现。 默认情况下，当你要求 Copilot 创建工作流时，其扩展仅在该会话中可用。 工作流也可能已经存储在个人扩展或项目扩展中。

若要复用或共享你在当前会话中创建的工作流，请将其扩展复制到你的个人扩展目录或代码仓库的扩展目录中。 这只会复制定义，不会复制运行历史记录或已保存的进度。

  1. 要求 Copilot 告知要共享的动态工作流的路径。 例如：

    Copilot prompt
    Tell me the path to the java-security-checks dynamic workflow.

Copilot 将响应路径，例如： /Users/yourname/.copilot/session-state/d58ba0bf-78fa-4172-b277-c18ba400e7c6/extensions/java-security-checks/extension.mjs

  1. 若要让此动态工作流在所有会话中都可用，请将包含 extension.mjs 文件的目录复制到 ~/.copilot/extensions/ 目录中。

    你可以要求 Copilot 你执行此操作。 例如：

    Copilot prompt
    Copy the java-security-checks workflow to my personal extensions directory.

  2. 或者，若要与存储库中工作的每个人共享动态工作流，请将包含 extension.mjs 文件的目录复制到您的存储库本地副本的 .github/extensions/ 目录中。

    同样，你可以让 Copilot 为你执行此操作。 例如，如果当前在要在其中提供动态工作流的存储库中工作：

    Copilot prompt
    Copy the java-security-checks workflow to the current repository's extensions directory.

    将此更改合并到存储库后，团队成员可以在更新本地副本并加载扩展后使用工作流。

  3. 启动新会话，或重启现有会话。 会话完成加载后，要求 Copilot 列出可用的动态工作流，以验证工作流现在是否可用。

在插件中分发动态工作流

插件提供了分发自定义 Copilot 功能的方法。 可以使用插件向和 添加动态工作流。

有关详细信息，请参阅“为 GitHub Copilot CLI 创建插件”。

创建包含动态工作流的插件并将其发布到插件市场后，用户将能够发现并安装它。 请参阅“查找并安装插件适用于GitHub Copilot CLI”。

监控和管理动态工作流运行情况

可以监视运行进度和 AI credits 使用情况，以及工作流报告的任何阶段和子智能体。 还可以检查已完成的运行、暂停或取消活动运行，并在达到限制时恢复已暂停或已停止的运行。

In Copilot CLI：

  1. 在交互式会话中，输入 /workflows。

    此处列出了当前正在运行和最近完成的动态工作流运行记录。

  2. 使用箭头键移动所选内容，然后按 Enter 打开运行的详细信息。

    详细信息包括：此次运行已处于活动状态的时长、工作流当前报告的阶段（如有）、当前处于活动状态的子代理数量、已生成的子代理总数，以及到目前为止已使用的 AI credits 数量。

  3. 在活动运行中，按 P 暂停， X 取消运行。

在Copilot app中：

注意

运行监视仅适用于本地会话。

如果您正在运行或曾在当前会话中运行动态工作流，则提示框上方会显示 工作流 按钮。

  1. 单击“ 工作流 ”按钮。

    此时会显示一个弹出窗口，其中列出了活动运行、准备恢复的运行以及最近完成的运行。

  2. 单击弹出窗口中的工作流运行。

    将显示一个面板，其中包含所选工作流运行的详细信息。

    详细信息包括运行处于活动状态的时间长度、工作流报告的任何当前阶段、当前活动子代理的数量、生成的子代理总数以及到目前为止使用的次数 AI credits 。

  3. 若要停止活动运行，请单击“ 取消”。 若要暂停它，以便以后可以恢复，请单击“ 暂停”。

使用 OTel 监控动态工作流

如果已启用 OpenTelemetry （OTel），则可以检查跟踪中的工作流活动。 工作流每次运行或恢复时都会创建一个 invoke_workflow 跨度，其代理的活动链接到它。

有关 Copilot CLI 中的配置，请参阅 GitHub Copilot CLI 命令参考。

恢复运行

可以恢复暂停的运行，也可以恢复在被列为可恢复状态时限制停止的运行。 工作流可以重复使用已完成的步骤和子代理中保存的结果，而不是启动新运行。 未保存的工作可能需要再次运行。

恢复因达到限制而中断的运行时，请提高该限制的总值。 本次运行停止前的使用量仍会计入新的总数。

无法恢复已取消的运行。

In Copilot CLI：

  1. 在交互式会话中，输入 /workflows。
  2. 使用箭头键将所选内容移动到要恢复的已暂停或停止运行。
  3. 按 R 恢复运行。
  4. 如果出现提示，请增加达到的限制并确认新总数。

在Copilot app中：

  1. 在包含已暂停或停止动态工作流运行的会话中，单击提示框正上方的 “工作流 ”按钮。

    任何可恢复的运行都列在“准备恢复”部分中。

  2. 单击要恢复的运行。

  3. 在侧面板中，单击 “恢复”。 如果运行达到限制，请单击 “恢复”，限制... 请改为按照提示设置更高的总计并恢复。

计划动态工作流运行

可以使用或/after命令在当前Copilot CLI会话中计划动态工作流运行，就像任何其他提示/every一样。 例如：

Copilot prompt
/every 1d run the changed-files-report dynamic workflow on the 'main' branch, limiting it to 200 AI credits

有关详细信息，请参阅“在 GitHub Copilot CLI 中安排提示”。