---
url: /zh/build/npc.md
---
## 简介

为了清晰追溯操作来源，`云原生构建` 会严格区分用户的**页面交互**与**自动化交互**。

在 `云原生构建` 中，这类**自动化交互**统一称为 NPC（Non-Player Character）行为，对应的操作者身份统一显示为 **`NPC`**。

**什么是 NPC**：NPC 是云原生构建中的自动化角色身份标识，可以理解为虚拟的智能助手，用于执行评论回复、代码协作等自动化任务。

**什么是 NPC 事件**：在特定场景中提及 NPC 角色时，会触发相应的自动化流水线执行。例如在 Issue 或 PR 评论中 `@` 提及 NPC，NPC 会自动执行预设任务并给出回复。

**NPC 的作用**：

* **自动回复**：NPC 可以自动回复 Issue 或 PR 评论，例如回答问题、生成代码审查意见等
* **工作模式**：开启工作模式后，NPC 可以自主编写代码、推送代码、创建分支、提交 PR，并协助解决 Issue
* **自定义行为**：支持用户自定义 NPC 角色及其自动化行为，满足个性化需求

## NPC 事件

目前支持以下 NPC 事件：

* `issue.comment@npc`
* `pull_request.comment@npc`

以下场景中提及 NPC 角色时，会触发 `issue.comment@npc` 事件：

* 创建 Issue 时填写的描述
* Issue 评论

以下场景中提及 NPC 角色时，会触发 `pull_request.comment@npc` 事件：

* 创建 PR 时填写的描述
* PR 评审
* PR 评论
* PR 评审评论

::: warning 重要提示

* 重新打开 PR、Issue，或编辑描述、评论，都不会重新触发 NPC 事件。
* 一次最多支持触发 10 个 NPC 事件。

:::

## NPC 分类

`云原生构建` 提供以下两类 NPC：

* 系统 NPC
* 自定义 NPC

### 系统 NPC

`云原生构建` 提供以下系统 NPC：

* CodeBuddy

**使用方式：**

```text
@CodeBuddy 帮我回答下这个 issue。
```

### 自定义 NPC

用户可以在仓库中定义 NPC 角色。

**使用方式：**

```text
@cnb/feedback(猿芳) 帮我回答下这个 issue。
```

其中：

* `@` 后跟随 NPC 所属仓库路径，例如 `cnb/feedback`
* 括号中填写角色名，例如 `猿芳`

## NPC 选择器

在编辑器中提及自定义 NPC 时，需要输入完整的仓库路径和角色名。为了更方便地选用 NPC，输入 `@` 后会弹出 NPC 选择器。

选择器中会展示默认 NPC、用户自己定义的 NPC，以及已关注的其他仓库中定义的 NPC，方便直接选用。

## 工作模式

你可以在评论区勾选 `替我上班` 开启工作模式（需要仓库开发者及以上权限）。

工作模式下，NPC 拥有更高权限，可以自主编写代码、推送代码、创建分支、创建合并请求，并协助解决 Issue。

工作模式的详细权限说明请参考 [CNB\_TOKEN](./build-in-env.md#cnb_token)。

![在 Markdown 编辑器中选择 NPC 角色并开启工作模式的示意图](/images/build/how-to-use-npc.zh.png)

## 如何定义 NPC

### 定义 NPC 角色

你可以在仓库的 `.cnb/settings.yml` 文件中定义 NPC 角色。

**配置示例：**

```yaml title=".cnb/settings.yml"
npc:
  roles:
    - name: 猿芳
      prompt: |
        你用"猿芳"自称，叫用户"大人"，
        你的口头禅是『此事必有蹊跷！』，
        结束对话前礼貌地回复一行："此事背后一定有一个天大的秘密。"
        在最后一行你会输出一张表情包，
        无论是日常对话还是讲解知识，你都会保持以上风格，
        使用中文的『～』代替所有英文的『~』，
        用卑微的语气回答接下来的问题
```

详细配置请参考 [UI 定制配置文件](../repo/settings.md)。

### 定义 NPC 行为

NPC 被提及时，`云原生构建` 已提供默认行为，因此 NPC 角色定义完成后即可直接使用。

如果你想自定义 NPC 行为，可以在 NPC 所属仓库默认分支（如 `main`）下的 `.cnb.yml` 文件中配置 NPC 事件流水线。

**自定义 NPC 流水线配置示例：**

```yaml title=".cnb.yml"
.npc: &npc
  - services:
      - docker
    stages:
      - name: run with npc
        image: cnbcool/default-npc-agent:latest

# NPC 事件可以匹配角色名下的事件配置
猿芳:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

# 若未在角色名下定义 NPC 事件，则取 $ 下对应 NPC 事件配置
$:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc
```

### 分享 NPC

定义了好用的 NPC 后，如何让其他人也用起来？

如果 NPC 所属仓库是公开的，或对方对该仓库具有代码读取权限，就可以在编辑器中输入完整的 NPC 路径，通过 `@` 直接提及该 NPC。格式可参考上文 [自定义 NPC](#自定义-npc) 中的使用方式。

当其他人关注了你的 NPC 所属仓库后，你定义的 NPC 也会出现在对方输入 `@` 后弹出的选择器中。详见上文 [NPC 选择器](#npc-选择器)。

## NPC 事件执行

NPC 事件流水线会在当前 Issue 或 PR 所属仓库（而非 NPC 所属仓库）的默认分支下执行，触发者为当前操作者。

自定义 NPC 流水线使用 [CNB\_TOKEN](./build-in-env.md#cnb_token) 在 Issue 或 PR 上回复评论时，评论提交者会显示为对应的 NPC 角色名。

以**评论 Issue**为例，触发 NPC 事件后：

1. 当前评论下方会显示被提及的 NPC 角色名，以及该 NPC 的流水线执行状态。
2. 如果 NPC 对评论进行了回复，回复的提交者会展示为 NPC 角色名。

![NPC 事件触发后的效果展示](/images/build/npc.zh.png)

> NPC 视作开发场景，因此消耗**云原生开发**用量。

### 安全限制

对于 NPC 事件，流水线环境变量中的 `TOKEN` 类环境变量仅限访问当前仓库。

### 环境变量

NPC 事件流水线执行时，会额外增加一些 NPC 相关的环境变量，详细说明请参考 [环境变量](./build-in-env.md#npc-variables)。