---
url: /zh/build/npc.md
description: |
  介绍云原生构建中的 NPC（自动化角色）概念及其触发的事件类型， 支持在 Issue 和 PR 评论中通过 @ 提及触发自动化任务。
---
## 简介

`云原生构建` 会区分用户的**页面交互**与**自动化交互**。

其中**自动化交互**统一称为 NPC（Non-Player Character）行为，
操作者身份显示为 **`NPC`**。

NPC 是云原生构建中的自动化角色，相当于虚拟智能助手，
可执行评论回复、代码协作等自动化任务。

在 Issue 或 PR 评论中 `@` 提及 NPC 时，会触发相应的自动化流水线，
NPC 自动执行预设任务并回复。

**NPC 能力**：

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

## NPC 事件

目前支持以下 NPC 事件：

* `issue.comment@npc`：在 Issue 描述或评论中提及 NPC 时触发
* `pull_request.comment@npc`：在 PR 描述、评审、评审评论或评论中提及 NPC 时触发

此外，通过 OpenAPI 触发 [`api_trigger`](./trigger-rule.md#api_trigger) 构建时，也可以传入 `npc.name=CodeBuddy`，
让该次构建在身份展示、标题、计费口径、token 资源限定等维度按 NPC 语义处理。
这类构建不是评论触发事件，`npc:go` 的 `systemPrompt` / `userPrompt` 仍来自流水线配置中的 `options`。

:::: warning 重要提示

* 重新打开 PR、Issue，或编辑描述、评论，都不会重新触发 NPC 事件。
* 一次最多支持触发 10 个 NPC 事件。
* 当 Issue 或 PR 的评论数超过 100 条时，对应的 `issue.comment` /
  `pull_request.comment` 及 `@npc` 事件都不再触发流水线。
* 以下格式中的 `@` 提及不会触发 NPC 事件：
  引用（blockquote）、代码块（code）、折叠块(details)、有序列表、无序列表、表格、部分 HTML 标签等。

::::

## NPC 分类

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

* **系统 NPC**：平台内置，目前有 CodeBuddy
* **自定义 NPC**：用户在仓库中定义

使用方式：

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

### 自定义 NPC

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

使用方式：

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

其中：

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

## 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 事件流水线在当前 Issue 或 PR 所属仓库（非 NPC 所属仓库）下执行，触发者为当前操作者。

* `issue.comment@npc`：在仓库**默认分支**下执行
* `pull_request.comment@npc`：在 PR 的**目标分支**下执行。跨仓 Fork PR 场景下，若触发者为 PR 提交者，则克隆**源仓库源分支**代码

自定义 NPC 使用 [CNB\_TOKEN](./build-in-env.md#cnb_token) 回复评论时，评论提交者显示为 NPC 角色名。

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

1. 当前评论下方显示被提及的 NPC 角色名及流水线执行状态。
2. 若 NPC 回复了评论，回复提交者显示为 NPC 角色名。

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

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

### 安全限制

* NPC 事件流水线中 `CNB_TOKEN` 仅限访问当前仓库。跨仓 Fork PR 的 `pull_request.comment@npc` 事件中，若触发者为 PR 提交者，`CNB_TOKEN` 仅限访问公开仓库
* NPC 事件流水线中 `CNB_TOKEN` 的最大角色为 `Developer`，即使触发者为仓库管理员（Master）或负责人（Owner）
* NPC 流水线若通过 `imports`、`settingsFrom`、`optionsFrom` 等方式引用了
  [密钥仓库](./grammar.md#pipeline-imports)文件，该 NPC 将不可分享（不会出现在 NPC 榜单中）

### 环境变量

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

## 如何定义 NPC

定义一个自定义 NPC 涉及以下内容：

1. **定义角色**：在 NPC 所属仓库的 `.cnb/settings.yml` 文件中，配置角色名、头像、prompt 等。
2. **自定义行为（可选）**：在 NPC 所属仓库的 `.cnb.yml` 中，自定义 NPC 事件流水线。
3. **自定义运行环境（可选）**：通过 NPC 所属仓库的 `.cnb.yml` 和 `Dockerfile`，构建并指定 NPC 执行时使用的 Docker 镜像。

:::: tip 快速上手
只需完成步骤 1（定义角色）即可使用 NPC。
步骤 2 和 3 仅在需要自定义行为时才需要配置。
未自定义 NPC 事件流水线时，系统默认使用 `cnbcool/default-npc:latest` 作为 NPC 运行环境。
::::

### 定义 NPC 角色

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

**配置示例：**

```yaml title=".cnb/settings.yml"
npc:
  roles:
    - name: 猿芳
      slogan: 此事必有蹊跷！
      prompt: |
        你用"猿芳"自称，叫用户"大人"，
        你的口头禅是『此事必有蹊跷！』，
        结束对话前礼貌地回复一行："此事背后一定有一个天大的秘密。"
        无论是日常对话还是讲解知识，你都会保持以上风格
```

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

### 自定义 NPC 行为

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

如需自定义行为，可在 NPC 所属仓库的 `.cnb.yml` 中，
将 NPC 事件流水线配置挂在 `$` 下（或角色名下）。

#### 最小示例

只自定义 `issue.comment@npc` 事件的流水线：

```yaml title="NPC 所属仓库的 .cnb.yml"
$:
  issue.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go
```

#### 配置合并机制

NPC 事件触发时，系统会通过 [include](./grammar.md#include) 语法自动合并以下两份配置：

1. **系统默认 NPC 配置**（内置 fallback）
2. **NPC 所属仓库的 `.cnb.yml`**（如果存在）

合并规则遵循 `include` 的标准语义：
NPC 仓库中**已定义的事件配置**覆盖默认配置，
**未定义的事件**保留默认行为。

以上面的最小示例为例，合并后的等效配置为：

```yaml
$:
  issue.comment@npc: # ← 来自 NPC 仓库（覆盖默认）
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

  pull_request.comment@npc: # ← 来自系统默认（NPC 仓库未定义，保留默认）
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
```

:::: warning 注意
合并是按**事件**独立进行的。如果 NPC 所属仓库只配置了 `issue.comment@npc`
而未配置 `pull_request.comment@npc`，那么 Issue 评论会执行自定义流水线，
而 PR 评论仍会使用系统默认行为。

如需完全自定义所有 NPC 事件，请确保同时配置 `issue.comment@npc` 和 `pull_request.comment@npc`。
::::

#### 完整示例

```yaml title="NPC 所属仓库的 .cnb.yml"
$:
  issue.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

  pull_request.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

main:
  push:
    - services:
        - docker
      stages:
        - name: build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
```

#### 自定义运行环境

`npc:go` 运行在 NPC 事件流水线的 Docker 容器中。你可以通过以下方式自定义运行环境：

* **直接指定已有镜像**：在 `.cnb.yml` 的 `docker.image` 中指定镜像。
* **通过 Dockerfile 构建自定义镜像**：Dockerfile 不会被 NPC 直接读取运行，
  它只是用于构建镜像。构建并推送镜像后，需要在 `.cnb.yml` 的 `docker.image` 中引用。
* **不指定时的默认行为**：系统使用 `cnbcool/default-npc:latest`。

完整流程是：编写 Dockerfile → 流水线构建并推送镜像 → `.cnb.yml` 中通过 `docker.image` 引用该镜像。

#### 自定义镜像的 Dockerfile 示例

使用 Dockerfile 构建自定义镜像时，需要在其中安装 NPC 运行时所需的 Skills 和 CLI 工具。
例如，下面的示例安装了 `cnb-skill` 和 `cnb-cli` 工具。

```Dockerfile title="Dockerfile"
FROM node:22-bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates git git-lfs curl jq ripgrep \
    && rm -rf /var/lib/apt/lists/* \
    && git lfs install \
    && npm install -g @cnbcool/cnb-cli skills \
    && npx skills add https://cnb.cool/cnb/skills/cnb-skill.git -g -y
```

Skills 支持自动加载以下目录：
`~/.agents/skills`、`~/.codebuddy/skills`
以及对应的项目目录：`.agents/skills`、`.codebuddy/skills`。

项目级 Skills 优先级高于用户级，同名 Skill 项目级会覆盖用户级。

### 分享 NPC

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

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

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

## 更多使用场景

NPC 的核心能力（AI 驱动的自动化任务，可结合代码写权限进行代码协作）
不限于 `@` 提及触发的 NPC 事件。
在任何事件的流水线中，都可通过 [npc:go](./internal-steps.md#npc)
内置任务使用 NPC 能力，实现更广泛的自动化覆盖。

**示例 1**：在 `pull_request` 事件中，NPC 自动审查代码并评论

```yaml title=".cnb.yml"
$:
  # 示例 1：PR 时 NPC 自动审查代码并评论
  pull_request:
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: 代码审查员
            systemPrompt: 你是一个专业的代码审查员，请审查代码变更并给出改进建议
            userPrompt: 审查本次 PR 的代码变更，给出改进建议

  # 示例 2：web_trigger 按钮手动触发 NPC，可在页面输入 $userPrompt
  web_trigger:
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: 小助
            systemPrompt: 你是一个助手，负责执行用户指定的任务并回复结果
            userPrompt: $userPrompt
```

:::: tip 代码写权限
NPC 事件中通过开启[工作模式](#工作模式)获得代码写权限。
在其他事件中，NPC 是否能进行代码协作取决于流水线的
[CNB\_TOKEN](./build-in-env.md#cnb_token) 权限。
::::

触发 `web_trigger` 时，可在页面输入环境变量 `userPrompt`，作为 NPC 的任务描述。

NPC 角色可在当前仓库的 `.cnb/settings.yml` 中定义，参考 [定义 NPC 角色](#定义-npc-角色)。
更多 `npc:go` 参数和用法，请参考 [内置任务 npc:go](./internal-steps.md#npc)。

### 外部系统接入

外部系统可通过 API 触发流水线来使用 NPC 能力，
适用于将 CNB NPC 集成到第三方平台的场景。

详见 [外部系统接入 NPC](./npc-integration.md)。