NPC 事件

2657 字约 9 分钟

简介

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

其中自动化交互统一称为 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 时触发

重要提示

重新打开 PR、Issue，或编辑描述、评论，都不会重新触发 NPC 事件。
一次最多支持触发 10 个 NPC 事件。
以下格式中的 @ 提及不会触发 NPC 事件：引用（blockquote）、代码块（code）、有序列表、无序列表、表格。

NPC 分类

云原生构建 提供两类 NPC：

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

使用方式：

@CodeBuddy 帮我回答下这个 issue。

自定义 NPC

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

使用方式：

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

其中：

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

NPC 选择器

在编辑器中输入 @ 会弹出 NPC 选择器，展示默认 NPC、当前用户自定义的 NPC 以及已关注仓库中的 NPC，方便直接选用。

工作模式

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

开启后 NPC 拥有更高权限，可自主编写代码、推送代码、创建分支、创建合并请求，并协助解决 Issue。

详细权限说明请参考 CNB_TOKEN。

NPC 事件执行

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

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

自定义 NPC 使用 CNB_TOKEN 回复评论时，评论提交者显示为 NPC 角色名。

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

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

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

安全限制

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

环境变量

NPC 事件流水线执行时，会额外注入一些 NPC 相关的环境变量，详细说明请参考环境变量。

如何定义 NPC

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

步骤	文件	位置	说明
1. 定义角色	`.cnb/settings.yml`	NPC 所属仓库	角色名、头像、prompt 等
2. 自定义行为（可选）	`.cnb.yml`	NPC 所属仓库	自定义 NPC 事件流水线
3. 自定义运行环境（可选）	`.cnb.yml` + `Dockerfile`	NPC 所属仓库	构建并指定 NPC 执行时使用的 Docker 镜像

快速上手

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

定义 NPC 角色

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

配置示例：

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

详细配置请参考 UI 定制配置文件。

自定义 NPC 行为

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

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

最小示例

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

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 语法自动合并以下两份配置：

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

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

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

$:
  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

注意

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

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

完整示例

同时自定义两个事件，并指定自定义镜像：

NPC 所属仓库的 .cnb.yml
.npc: &npc
  - docker:
      # 指定镜像，内含 NPC 运行时需要的 CLI 工具和 Skills
      image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
    stages:
      - name: npc go
        type: npc:go

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

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

# 构建并推送 Docker 镜像
main:
  push:
    - services:
        - docker
      stages:
        - name: Docker build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: Docker 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
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 分类

自定义 NPC

NPC 选择器

工作模式

NPC 事件执行

安全限制

环境变量

如何定义 NPC

定义 NPC 角色

自定义 NPC 行为

最小示例

配置合并机制

完整示例

自定义运行环境

自定义镜像的 Dockerfile 示例

分享 NPC

更多使用场景

外部系统接入