CNB 文档

简体中文

English

简体中文

English

外观

NPC 事件

复制页面

2655 字约 9 分钟

简介

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

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

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

如何定义 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

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

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

分享 NPC

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

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

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

NPC 事件执行

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

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

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

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

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

安全限制

对于非跨仓 PR 场景下触发的 NPC 事件，流水线环境变量中的 TOKEN 类环境变量仅限访问当前仓库。

环境变量

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

外部系统接入 NPC

CNB 的 NPC 执行时，会启动一个流水线作为沙箱环境，并在沙箱环境运行任务。

外部系统可通过 OPENAPI 触发流水线， 并自定义 NPC 的角色、运行环境、SKills、Prompt 等，来使用 CNB 的 NPC 能力。

时序图如下：

配置步骤

  1. 在仓库的 .cnb/settings.yml 文件中定义 NPC 角色，定义语气、风格等。
.cnb/settings.yml
npc:
  defaultRole: 小助
  roles:
    - name: 小助
      prompt: |
        你用“小助”自称，叫用户“朋友”，
        你的口头禅是『收到，马上处理！』，
        结束对话前礼貌的回复一行：“任务完成，随时待命！还有其它问题么？\n”，
        无论是日常对话还是讲解知识，你都会保持以上风格，
        所有的表情包使用markdown语法输出，
        用热情的语气回答接下来的问题
  1. 定义 NPC 运行环境

在 Dockerfile 中，需要安装 NPC 运行时需要的 Skills 和 CLI 工具。例如，下面的示例安装了 cnb-skill 和 cnb-cli 工具。

按需安装外部工具需要使用的依赖、CLI 和 Skills， 特别是需要封装 NPC 运行后的结果如何发送给外部系统的 Skills 和 prompt。

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
  1. 定义 NPC 事件流水线
.cnb.yml
# 定义 API 触发流水线， 注意事件名需要以 api_trigger_ 开头
api_trigger_npc:
  - docker:
      image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
    # 沙箱模式：开启后 CNB_TOKEN、CNB_TOKEN_FOR_AI 将无效
    sandbox: true
    stages:
      - name: npc go
        type: npc:go
        options:
          role: $role
          systemPrompt: $systemPrompt
          userPrompt: $userPrompt

# 构建并推送 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
  1. 调用 API 触发流水线，更多参数请参考 OPENAPI。 触发后可以在 CNB 云原生构建的流水线列表中看到对应的流水线，并查看流水线执行情况。
curl --request POST \
  --url 'https://api.cnb.cool/{repo}/-/build/start' \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "event": "api_trigger_npc",
    "env": {
      "role": "角色名",
      "systemPrompt": "你是一个自动化助手，负责执行用户指定的任务，结果通过企业微信机器人发送给用户，企业微信机器人的 webhook 地址是...",
      "userPrompt": "帮我查一下今天深圳天气"
    }
  }'

参数说明

通过 env 字段传递以下参数，详细说明请参考 npc:go 参数说明 和 api_trigger 参数。

参数类型必填说明
roleString是NPC 角色名称，定义语气、风格，需在仓库 .cnb/settings.yml 的 npc.roles 中定义, 例如 小助
systemPromptString是系统提示词，用于定义 NPC 的行为指引， 包括拿到下面的 userPrompt 作为用户输入后，NPC 如何一步一步执行，最终如何将结果发送给外部系统等，例如 你是一个自动化助手，负责执行用户指定的任务，结果通过企业微信机器人发送给用户
userPromptString是用户输入，用于向 NPC 描述具体任务， 例如 帮我查一下今天深圳天气

沙箱模式说明

开启沙箱模式后，NPC 运行在隔离的安全环境中，流水线中的 CNB_TOKEN 和 CNB_TOKEN_FOR_AI 将无效，因此无法调用 CNB API 和操作 CNB 平台资源，例如无法提交代码、评论 Issue 等。

如果 NPC 需要执行代码提交、评论 Issue 等平台操作，请关闭沙箱模式。

© 2026 cnb.cool