# 使用深层链接打开 GitHub Copilot 应用

使用深层链接从终端、票证和内部工具启动 GitHub Copilot 应用 ，以便用户可以直接跳入正确的存储库、拉取请求、自动化或会话。

深度链接可帮助人们在 GitHub Copilot 应用 中减少上下文切换，更快开始工作。 例如，可以共享启动提示、在 markdown 文件中包括指向应用的链接、从终端脚本启动应用，或添加一个按钮以在外部工具中打开应用。

您可以在托管启动器中，通过封装了应用链接的浏览器链接打开 GitHub Copilot 应用。 托管启动器会在可能时打开应用；如果浏览器无法将控制权交给该应用，则会显示后备页面。 有关支持的应用链接的完整列表，请参阅 [“可用应用链接](#available-app-links)”。

## 为何使用深层链接

如果要直接从网页或工作流移动到应用中的特定页面或任务，请使用深层链接。 常见用例包括：

* 使用预先填充的启动提示启动会话。
* 共享自动化提示，以便团队成员可以快速打开和重复使用它们。
* 在内部文档或 Markdown 文件中添加启动按钮以打开常见工作流。
* 从终端命令或脚本作为本地工作流的一部分启动应用。
* 从问题跟踪系统或工单系统等第三方产品中打开应用。

## 启动器 URL 格式

将托管启动器 URL 与查询参数中 `open` 编码的完整应用链接配合使用。 托管启动器会在可能的情况下打开该应用；如果浏览器无法将请求转交给该应用，则会显示后备页面。

```text
https://github.com/copilot/app/launch?open=ENCODED_APP_LINK
```

使用 `encodeURIComponent`编程语言或等效语言对完整的应用链接进行编码。 如果应用链接包含查询参数，在编码完整的应用链接 `open`之前，请对这些查询参数值进行编码。

例如，若要打开存储库，应用链接为：

```text
ghapp://github.com/OWNER/REPO
```

将其编码到启动器 URL 中后，就变成：

```text
https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fgithub.com%2FOWNER%2FREPO
```

公共链接应使用官方 `ghapp://` 计划。 应用还接受 `github-app://` 并 `gh://` 链接以保持兼容性，但生成的链接和记录的链接应使用 `ghapp://`。

## 打开存储库或工作项

若要在 GitHub Copilot 应用 中打开某个页面，请使用要打开页面的应用链接构建启动器 URL。

* 若要打开存储库，请使用以下应用链接：

   ```text
   ghapp://github.com/OWNER/REPO
   ```

   将其编码到启动器 URL 中后，就变成：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fgithub.com%2FOWNER%2FREPO
   ```

* 若要提交问题，请使用此应用链接：

   ```text
   ghapp://github.com/OWNER/REPO/issues/NUMBER
   ```

   将其编码到启动器 URL 中后，就变成：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fgithub.com%2FOWNER%2FREPO%2Fissues%2F123
   ```

* 若要打开拉取请求，请使用以下应用链接：

   ```text
   ghapp://github.com/OWNER/REPO/pull/NUMBER
   ```

   将其编码到启动器 URL 中后，就变成：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fgithub.com%2FOWNER%2FREPO%2Fpull%2F123
   ```

* 若要恢复代理任务，请使用以下应用链接：

   ```text
   ghapp://github.com/OWNER/REPO/tasks/TASK_ID
   ```

   将其编码到启动器 URL 中后，就变成：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fgithub.com%2FOWNER%2FREPO%2Ftasks%2FTASK_ID
   ```

   将 GitHub 任务 ID 用于 `TASK_ID`。 不要在用于恢复 GitHubCopilot 代理任务的链接中使用运行时会话 ID 或应用本地会话 URL。

## 打开会话

若要从深层链接启动新会话，请使用 `ghapp://session/new` 查询参数来预填充存储库、分支、拉取请求、提示或模式。 有关可用参数，请参阅 [会话参数](#session-parameters)。

例如，若要使用存储库和启动提示启动新的交互式会话，请使用以下应用链接：

```text
ghapp://session/new?repo=OWNER%2FREPO&mode=interactive&prompt=Investigate%20failing%20tests
```

将其编码到启动器 URL 中后，就变成：

```text
https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fsession%2Fnew%3Frepo%3DOWNER%252FREPO%26mode%3Dinteractive%26prompt%3DInvestigate%2520failing%2520tests
```

### 会话参数

链接`ghapp://session/new``ghapp://session/new/OWNER/REPO`接受这些查询参数。

| 参数 | 必需 | 备注 |
| --- | --- | --- |
| `repo` | 
`ghapp://session/new` 为必填项；`ghapp://session/new/OWNER/REPO` 为可选项 | 
`OWNER/REPO` 格式的存储库。 |
| `pr` | 否 | 拉取请求编号为正数。 不能与 `branch`.. |
| `branch` | 否 | 新会话的基分支。 不能与 `pr`。 |
| `prompt` | 否 | 启动提示。 不要在 URL 中包含机密或敏感用户内容。 |
| `mode` | 否 | 
`plan`、`interactive`、或`autopilot`之一。 |

## 打开自动化功能

若要打开自动化或从深层链接创建新的自动化草稿，请使用自动化应用链接。 有关创建新自动化草稿时可用的参数，请参阅 [自动化参数](#automation-parameters)。

* 若要打开“自动化”页，请使用以下应用链接：

   ```text
   ghapp://automations
   ```

   将其编码到启动器 URL 中后，结果如下所示：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fautomations
   ```

* 若要打开新的自动化草稿，请使用以下应用链接：

   ```text
   ghapp://automations/new?name=Daily%20triage&trigger=daily&time=09%3A00&prompt=Summarize%20new%20issues
   ```

   将其编码到启动器 URL 中后，就变为：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fautomations%2Fnew%3Fname%3DDaily%2520triage%26trigger%3Ddaily%26time%3D09%253A00%26prompt%3DSummarize%2520new%2520issues
   ```

* 若要打开现有自动化，请使用以下应用链接：

   ```text
   ghapp://automations/AUTOMATION_ID
   ```

   将其编码到启动器 URL 中后，则变为：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fautomations%2FAUTOMATION_ID
   ```

* 若要打开云端自动化，请先将 `mode=cloud` 添加到应用链接前面，再对其进行编码：

   ```text
   ghapp://automations/AUTOMATION_ID?mode=cloud
   ```

   将其编码到启动器 URL 中后，就会变成：

   ```text
   https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fautomations%2FAUTOMATION_ID%3Fmode%3Dcloud
   ```

### 自动化参数

该 `ghapp://automations/new` 链接将打开新的自动化对话框。 在用户查看对话框并在应用中确认之前，它不会创建自动化。 不要在 URL 中嵌入的提示中包含机密或敏感用户内容。

| 参数 | 适用对象 | 备注 |
| --- | --- | --- |
| `name` | `ghapp://automations/new` | 自动化名称。 |
| `prompt` | `ghapp://automations/new` | 自动化提示。 不要在 URL 中包含机密或敏感用户内容。 |
| `trigger` | `ghapp://automations/new` | 其中之一为`manual`、`hourly`、`daily`或`weekly`。 无效值会被忽略。 
`interval` 也接受为别名。 |
| `time` | `ghapp://automations/new` | 
`HH:mm` 采用本地 24 小时制格式的时间。 可用于 `daily` 和 `weekly` 触发器。 例如，当所有条目共享同一分钟时， `time=08:00,13:00`每日触发器也接受逗号分隔或重复时间。 无效值会被忽略。 |
| `day` | `ghapp://automations/new` | 每周日期（`0`-`6``0`= 星期日）或工作日名称。 无效值会被忽略。 
`schedule_day` 也可用作别名，并且每周触发器支持以逗号分隔的值或重复指定的值，例如 `schedule_day=1,3,5`。 |
| `mode` | 
`ghapp://automations/AUTOMATION_ID` 和 `ghapp://automations/AUTOMATION_ID/RUN_ID` | 将 `cloud` 用于云自动化。 省略它，或对本地自动化使用 `local`。 |

## 打开插件流

若要从深层链接打开插件安装或市场流，请使用插件应用链接。 有关可用参数，请参阅 [插件参数](#plugin-parameters)。

例如，若要使用预填充的源打开插件安装表单，请使用以下应用链接：

```text
ghapp://plugins/install?source=my-plugin%40acme
```

将其编码到启动器 URL 中后，就变成：

```text
https://github.com/copilot/app/launch?open=ghapp%3A%2F%2Fplugins%2Finstall%3Fsource%3Dmy-plugin%2540acme
```

### 插件参数

插件链接会打开“设置”>“插件”，并预先填充表单。 在用户确认应用之前，他们不会安装插件或添加市场。

| Link | 参数 | 必需 | 备注 |
| --- | --- | --- | --- |
| `ghapp://plugins/install` | `source` | 是的 | 采用 `PLUGIN@MARKETPLACE` 格式的插件源。 对该值进行 URL 编码，例如 `source=my-plugin%40acme`。 |
| `ghapp://plugins/marketplace/add` | `source` | 是的 | 将应用市场源指定为 `OWNER/REPO` 或 Git URL。 对该值进行 URL 编码，例如 `source=acme%2Fplugins`。 |

## 可用的应用链接

以下应用链接可以包装在托管启动器中。 当应用打开链接时，将保留查询字符串和哈希。

| 应用链接形状 | 打开 | 备注 |
| --- | --- | --- |
| `ghapp://` | 主 | 打开应用主页路由。 |
| `ghapp://chats` | 聊天 | 打开聊天。 |
| `ghapp://mywork` | 我的工作 | 在“我的工作”中打开问题和拉取请求。 |
| `ghapp://github.com/OWNER/REPO` | 存储库设置 | 打开或克隆存储库。 |
| `ghapp://github.com/OWNER/REPO/issues/NUMBER` | 问题 | 在已将存储库添加为项目时，在“我的工作”中打开问题。 |
| `ghapp://github.com/OWNER/REPO/pull/NUMBER` | 拉取请求 | 将存储库添加为项目时，在“我的工作”中打开拉取请求。 保留可选的尾随路径段。 |
| `ghapp://github.com/OWNER/REPO/tasks/TASK_ID` | 代理任务 | 
GitHub
Copilot恢复代理任务。 请使用GitHub任务 ID，而不是应用内会话 ID。 |
| `ghapp://automations` | Automations | 打开自动化功能。 |
| `ghapp://automations/new` | 新自动化草稿 | 打开新的自动化对话框，其中预先填充了支持的查询参数。 请参阅 [自动化参数](#automation-parameters)。 |
| `ghapp://automations/AUTOMATION_ID` | 自动化 | 默认情况下，打开本地自动化。 为云自动化添加 `?mode=cloud` 。 |
| `ghapp://automations/AUTOMATION_ID/RUN_ID` | 自动化运行 | 默认情况下开启本地自动化运行。 为云自动化运行添加 `?mode=cloud` 。 |
| `ghapp://recent` | 最近使用的工作区 | 打开最近的工作区。 |
| `ghapp://sessions/SESSION_ID` | 应用会话 | 打开应用本地工作区或会话。 请勿使用此形状来继续 GitHub Copilot 代理任务。 |
| `ghapp://clone/OWNER/REPO` | 存储库设置 | 在克隆或打开存储库设置之前显示确认。 |
| `ghapp://repo/OWNER/REPO` | 存储库设置 | 在克隆或打开存储库设置之前显示确认。 |
| `ghapp://session/new` | 新会话 | 在创建会话之前显示确认信息。 使用查询参数提供存储库、拉取请求、分支、提示或会话模式。 请参阅 [会话参数](#session-parameters)。 |
| `ghapp://session/new/OWNER/REPO` | 存储库的新会话 | 在为存储库创建会话之前显示确认。 请参阅 [会话参数](#session-parameters)。 |
| `ghapp://plugins/install` | 插件安装表单 | 显示确认提示，然后打开“设置”>“插件”，并预先填好安装表单。 请参阅 [插件参数](#plugin-parameters)。 |
| `ghapp://plugins/marketplace/add` | 插件市场表单 | 显示确认提示，然后打开“设置”>“插件”，并预先填充市场表单。 请参阅 [插件参数](#plugin-parameters)。 |