NPC 事件

1650 字约 6 分钟

简介

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

在 云原生构建 中，这类自动化交互统一称为 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 评审评论

重要提示

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

NPC 分类

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

系统 NPC
自定义 NPC

系统 NPC

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

CodeBuddy

使用方式：

@CodeBuddy 帮我回答下这个 issue。

自定义 NPC

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

使用方式：

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

其中：

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

NPC 选择器

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

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

工作模式

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

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

工作模式的详细权限说明请参考 CNB_TOKEN。

如何定义 NPC

定义 NPC 角色

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

配置示例：

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

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

定义 NPC 行为

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

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

1. 自定义 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

2. 构建 NPC 运行时镜像：

在 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