# 以编程方式运行GitHub Copilot CLI

Copilot CLI在终端、脚本或 Actions 工作流中使用。

## 介绍

可以直接在单个命令中传递提示 Copilot CLI ，而无需输入交互式会话。 这允许直接从终端使用 Copilot ，但也允许在脚本、CI/CD 管道和自动化工作流中以编程方式使用 CLI。

若要以编程方式使用 Copilot CLI ，可以执行以下任一操作。

* 将 `copilot` 命令与 `-p` 或 `--prompt` 命令行选项一起使用，后跟提示：

  ```shell copy
  copilot -p "Explain this file: ./complex.ts"
  ```

* 通过管道将提示传递给 `copilot` 命令：

  ```shell copy
  echo "Explain this file: ./complex.ts" | copilot
  ```

  > \[!NOTE]
  > 如果您还提供了带有 `-p` 或 `--prompt` 选项的提示，则管道输入将被忽略。

## 以编程方式使用 Copilot CLI 的提示

* **提供精确的提示** — 清晰明确的指令比模糊的请求产生更好的结果。 你提供的上下文越多 - 文件名、函数名、确切更改，Copilot 所需的猜测就越少。
* **谨慎地引用提示** — 如果你想避免 shell 对特殊字符的解释，请在提示符周围使用单引号。
* **始终授予最小权限** - 使用`--allow-tool=[TOOLS...]``--allow-url=[URLs...]`命令行选项授予Copilot仅使用完成任务所需的工具和访问权限的权限。 除非你在沙盒环境中工作，否则请避免使用过于宽松的选项（例如 `--allow-all`）。 有关详细信息，请参阅“[关于云和本地沙盒 GitHub Copilot](/zh/copilot/concepts/about-cloud-and-local-sandboxes)”。
* 捕获输出时**使用`-s`（静默模式）**。 这会取消会话元数据，以便获取干净的文本。
* **使用 `--no-ask-user`** 以防止代理尝试提出澄清的问题。
* **明确设置模型**，并为其指定 `--model`，以确保在不同环境中行为的一致性。

有关以编程方式运行[](/zh/copilot/reference/copilot-cli-reference/cli-programmatic-reference)时特别有用的选项，请参阅 Copilot CLI。

## CI/CD 集成

以编程方式运行的 Copilot CLI 常见用例是在 CI/CD 工作流步骤中包含 CLI 命令。

从 GitHub Actions 工作流中提取出的内容显示了运行 Copilot CLI 命令的简单示例。

```yaml
# Workflow step using Copilot CLI
- name: Generate test coverage report
  env:
    COPILOT_GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
  run: |
    copilot -p "Run the test suite and produce a coverage summary" \
      -s --allow-tool='shell(npm:*), write' --no-ask-user
```

有关详细信息，请参阅“[使用 Copilot CLI 和 GitHub Actions 自动执行任务](/zh/copilot/how-tos/copilot-cli/automate-copilot-cli/automate-with-actions)”。

## 编程用法示例

### 生成提交消息

```bash copy
copilot -p 'Write a commit message in plain text for the staged changes' -s \
  --allow-tool='shell(git:*)'
```

### 汇总文件

```bash copy
copilot -p 'Summarize what src/auth/login.ts does in no more than 100 words' -s
```

### 为模块编写测试

```bash copy
copilot -p 'Write unit tests for src/utils/validators.ts' \
  --allow-tool='write, shell(npm:*), shell(npx:*)'
```

### 修复 Lint 错误

```bash copy
copilot -p 'Fix all ESLint errors in this project' \
  --allow-tool='write, shell(npm:*), shell(npx:*), shell(git:*)'
```

### 说明差异

```bash copy
copilot -p 'Explain the changes in the latest commit on this branch and flag any potential issues' -s
```

### 对分支进行代码审查

使用 `/review` 斜杠命令让内置 `code-review` 代理查看当前分支上的代码更改。

```bash copy
copilot -p '/review the changes on this branch compared to main. Focus on bugs and security issues.' \
  -s --allow-tool='shell(git:*)'
```

### 生成文档

```bash copy
copilot -p 'Generate JSDoc comments for all exported functions in src/api/' \
  --allow-tool=write
```

### 导出会话

将完整会话脚本保存到本地文件系统上的 Markdown 文件。

```bash copy
copilot -p "Audit this project's dependencies for vulnerabilities" \
  --allow-tool='shell(npm:*), shell(npx:*)' \
  --share='./audit-report.md'
```

将会话记录保存到 GitHub.com 上的要点，方便共享。

```bash copy
copilot -p 'Summarize the architecture of this project' --share-gist
```

> \[!NOTE]
> 要点不适用于 Enterprise Managed Users，或你使用带数据驻留的 GitHub Enterprise Cloud (\*.ghe.com) 时。

## Shell 脚本模式

### 捕获 Copilot 的输出并存入变量中

```bash copy
result=$(copilot -p 'What version of Node.js does this project require? \
  Give the number only. No other text.' -s)
echo "Required Node version: $result"
```

### 在条件中使用

```bash copy
if copilot -p 'Does this project have any TypeScript errors? Reply only YES or NO.' -s \
  | grep -qi "no"; then
  echo "No type errors found."
else
  echo "Type errors detected."
fi
```

### 处理多个文件

```bash copy
for file in src/api/*.ts; do
  echo "--- Reviewing $file ---" | tee -a review-results.md
  copilot -p "Review $file for error handling issues" -s --allow-all-tools | tee -a review-results.md
done
```

## 延伸阅读

* [GitHub Copilot CLI](/zh/copilot/how-tos/copilot-cli)
* [GitHub Copilot 命令行界面编程参考](/zh/copilot/reference/copilot-cli-reference/cli-programmatic-reference)
* [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference#command-line-options)