CNB 文档

简体中文

English

简体中文

English

外观

NPC 事件

复制页面

2683 字约 9 分钟

简介

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

在 云原生构建 中，这类自动化交互统一称为 NPC（Non-Player Character）行为，操作者身份统一显示为 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 事件：引用（blockquote）、代码块（code）、有序列表、无序列表、表格。

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。

在 Markdown 编辑器中选择 NPC 角色并开启工作模式的示意图
在 Markdown 编辑器中选择 NPC 角色并开启工作模式的示意图

NPC 事件执行

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

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

自定义 NPC 流水线使用 CNB_TOKEN 在 Issue 或 PR 上回复评论时，评论提交者会显示为对应的 NPC 角色名。

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

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

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

安全限制

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

环境变量

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

如何定义 NPC

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

步骤文件位置说明
1. 定义角色.cnb/settings.ymlNPC 所属仓库角色名、头像、prompt 等
2. 自定义行为（可选）.cnb.ymlNPC 所属仓库自定义 NPC 事件流水线
3. 定义运行环境（可选）DockerfileNPC 所属仓库安装 NPC 运行时所需工具

快速上手

只需完成步骤 1（定义角色）即可使用 NPC。步骤 2 和 3 仅在需要自定义行为时才需要配置。

定义 NPC 角色

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

配置示例：

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

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

自定义 NPC 行为

NPC 被提及时，云原生构建 已提供默认行为，因此 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 语法自动合并以下两份配置：

  1. 系统默认 NPC 配置（内置 fallback）
  2. 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

定义运行环境

在 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 的核心能力（AI 驱动的自动化任务，可结合代码写权限进行代码协作） 不限于 @ 提及触发的 NPC 事件。 在任何事件的流水线中，都可以通过 npc:go 内置任务来使用 NPC 能力，实现更广泛的自动化覆盖。

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

.cnb.yml
$:
  pull_request:
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: 代码审查员
            systemPrompt: 你是一个专业的代码审查员，请审查代码变更并给出改进建议
            userPrompt: 审查本次 PR 的代码变更，给出改进建议

示例 2：通过 web_trigger 按钮手动触发 NPC 执行任务

.cnb.yml
$:
  web_trigger:
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: 小助
            systemPrompt: 你是一个助手，负责执行用户指定的任务并回复结果
            userPrompt: $userPrompt

代码写权限

NPC 事件中通过开启工作模式获得代码写权限。 在其他事件中，NPC 是否能进行代码协作取决于流水线的 CNB_TOKEN 权限。

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

NPC 角色可在当前仓库的 .cnb/settings.yml 中定义，参考 定义 NPC 角色。 更多 npc:go 参数和用法，请参考 内置任务 npc:go。

外部系统接入

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

详见 外部系统接入 NPC。

© 2026 cnb.cool