NPC

4585 字约 15 分钟

快速上手

在 Issue 或 PR 的评论中 @CodeBuddy 并说出需求，它会自动执行并回复：

@CodeBuddy 帮我实现这个 Issue
@CodeBuddy 帮我审查一下这个 PR 的代码

@CodeBuddy 是系统内置 NPC，开箱即用。

定义自己的 NPC

在仓库 .cnb/settings.yml 里配置角色，即可通过 @仓库路径(角色名) 使用：

.cnb/settings.yml
npc:
  roles:
    - name: 专家
      prompt: |
        你以"专家"自称，致力于提供专业、准确的技术解答。

@<你的仓库路径>(专家) 帮我回答下这个 issue。

将 <你的仓库路径> 替换为实际路径，例如 your-group/your-repo。系统会使用默认运行环境（cnbcool/default-npc:latest），无需额外配置 .cnb.yml 或 Dockerfile。

如需进一步指定运行镜像、模型或注入自定义提示词，见自定义 NPC。

理解 NPC

上手之后，这一部分带你搞懂 NPC 到底是什么、有哪几类，以及如何选用。

什么是 NPC

NPC（Non-Player Character）是云原生构建中的自动化角色——虚拟智能助手，可以替你回复评论、协作代码等。

云原生构建把用户操作分为两类：手动点击、编辑的页面交互，以及 NPC 代你完成的自动化交互。后者的操作者身份统一显示为 NPC，与真人区分。

@ 提及 NPC 时，平台会为它启动一条流水线，由 NPC 在其中执行任务并回复。

委托代理模型

NPC 代你操作，本质上是一次委托：你把任务托付给 NPC， NPC 以你的名义在限定范围内代办。云原生构建为这层关系定义了三个术语：

当事人（principal）：发起委托的用户，即 @ 提及 NPC 的操作者。平台按当事人的角色为 NPC 流水线签发临时令牌。
代理人（agent）：受托执行任务的 NPC，以当事人名义在限定范围内代办，对外展示为 NPC 身份。
代理权（delegated authority）：当事人授予代理人的权限范围，受三重约束—— 限时（仅本次任务）、限地（仅限当前仓库）、限权（角色上限与 scope 收窄）。任务结束或流水线销毁时自动终止。

NPC 能力

NPC 能做的事分为三层，由浅入深：

自动回复：回答评论区问题、给出代码审查意见等文字回复
工作模式：开启后 NPC 可自主写代码、推代码、建分支、发 PR、按评审意见修改，闭环解决 Issue
自定义行为：定义 NPC 的角色人设与运行方式

两类 NPC

云原生构建里有两类 NPC：

系统 NPC——平台内置，目前是 CodeBuddy，通过 @CodeBuddy 直接使用。
自定义 NPC——用户在自己的仓库中定义的角色，通过 @仓库路径(角色名) 提及：

@<你的仓库路径>(专家) 帮我回答下这个 issue。

@ 后是 NPC 所属仓库路径（如 your-group/your-repo），括号里是角色名（如 专家），两者共同定位到一个具体的 NPC。

NPC 选择器

在评论编辑器中输入 @ 即可弹出 NPC 选择器，其中列出了系统 NPC、你定义的 NPC，以及你关注仓库中的 NPC，点选即可提及。

工作模式

默认情况下，NPC 只能读代码、写评论。如需让它完成开发闭环（写代码、推代码、发 PR），在评论区勾选 替我上班 开启工作模式，即可授予更高权限。

开启工作模式需要仓库 开发者及以上 权限。开启后，NPC 可自主：

编写代码、推送代码、创建分支
创建合并请求（PR）
按 PR 评审意见修改代码
协助解决 Issue

详细令牌权限说明见 CNB_TOKEN。

NPC 事件

@ 提及 NPC 时启动的那条流水线，就是由NPC 事件触发的。这一节展开讲：都有哪些 NPC 事件、如何执行、以及配套的安全限制。

事件类型

目前 NPC 事件都由评论触发，共两种：

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

重要提示

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

事件执行

NPC 事件触发的流水线，有几个关键点：

执行位置：流水线跑在当前 Issue 或 PR 所属仓库下（不是 NPC 所属仓库）；触发者是当前操作用户（即委托代理模型中的当事人）。
代码分支：
- issue.comment@npc：在仓库默认分支下执行
- pull_request.comment@npc：
  - 默认在 PR 的目标分支下执行；跨仓 Fork PR 且触发者为 PR 提交者时，克隆源仓库源分支代码
  - PR 已合并时，克隆合并后 commit 的代码（源分支可能已删除），CNB_COMMIT 即合并后的 sha，可配合 git cherry-pick 把提交同步到其他分支
结果呈现（以评论 Issue 为例）：
1. 当前评论下方显示被提及的 NPC 角色名及流水线执行状态
2. 若 NPC 使用 CNB_TOKEN 回复了评论，评论提交者显示为 NPC 角色名
计费口径：NPC 视作开发场景，消耗云原生开发用量。

安全限制

以下限制是委托代理模型中限地与限权约束的具体体现：

仓库范围：NPC 事件流水线中 CNB_TOKEN 默认仅限访问当前仓库。跨仓 Fork PR 的 pull_request.comment@npc 事件中，若触发者为 PR 提交者，CNB_TOKEN 仅限访问公开仓库。
角色上限：CNB_TOKEN 的最大角色取决于触发用户在仓库中的角色：
- Developer / Master / Owner → 最大角色 Developer
- Reporter / Guest → 最大角色 Reporter，且无法启用工作模式
密钥引用：NPC 流水线若通过 imports、settingsFrom、optionsFrom 等方式引用了密钥仓库文件，该 NPC 将不可分享（不会出现在 NPC 榜单中）。

允许 NPC 跨仓操作

安全限制中的"仓库范围"是默认策略，可以由根组织管理员显式放宽。

在组织设置中开启 「允许 NPC 跨仓操作」 开关后， NPC 事件流水线的 CNB_TOKEN 访问范围从"当前仓库"扩大到"当前根组织下的所有仓库"， NPC 就能自动处理跨仓协作任务（如跨仓库读取代码、发起 PR 等）。

边界说明

只放宽限地约束，不改变限权（角色上限）与限时（任务/流水线生命周期）约束。
放宽范围为根组织内：仍不允许跨根组织访问。
跨仓 Fork PR 场景（PR 提交者触发）仍走公开仓库限制，不受此开关影响。

环境变量

NPC 事件流水线执行时，除通用环境变量外，还会注入 CNB_NPC_* 系列变量，包含 NPC 角色名、所属仓库、当前 Issue/PR 上下文等，便于流水线中读取和使用。

完整变量清单请参考环境变量。

自定义 NPC

NPC 可以逐步定制，让它更贴合你的需求：

定义角色（必选）：在 NPC 所属仓库的 .cnb/settings.yml 中，配置角色名、头像、prompt 等。只做这一步 NPC 就能用起来—— 系统默认运行环境（cnbcool/default-npc:latest）会兜底后面的步骤。
自定义行为（可选）：在 NPC 所属仓库的 .cnb.yml 中，定义 NPC 事件流水线，控制 NPC 被 @ 时具体做什么。
自定义运行环境（可选）：通过 .cnb.yml + Dockerfile，构建并指定 NPC 执行时使用的 Docker 镜像。

如果你已经按照上文快速上手定义过角色，可直接从第 2 步开始。

建议

每完成一步，在 Issue 评论中 @ 该 NPC 验证效果，再继续下一步——比一次配到位更容易排查问题。

定义 NPC 角色

在仓库的 .cnb/settings.yml 中，通过 npc.roles 列表定义一个或多个角色：

.cnb/settings.yml
npc:
  roles:
    - name: 专家
      slogan: 专业解答，高效协助
      prompt: |
        你以"专家"自称，致力于提供专业、准确的技术解答。
        回复时保持简洁专业，引用可靠来源。
        无论是日常对话还是讲解知识，你都会保持以上风格

name：角色名，@ 提及时使用（如 @your-group/your-repo(专家)）
slogan：角色标语，展示在 NPC 卡片和榜单中
prompt：给 NPC 的系统提示词，决定它的人设与回复风格

更多可配置项（头像等）详见 UI 定制配置文件。

自定义 NPC 行为

角色定义好后，NPC 已经具备默认响应行为（默认镜像 + npc:go 内置任务，执行任务并回复评论）。如果默认行为够用，可以跳过本小节。

常见需要自定义的场景：使用自己构建的 NPC 镜像、在流水线中准备运行环境（如 Skill 加载、预装编程语言、各种工具命令等）、或按角色区分不同的响应流程。

做法：在 NPC 所属仓库的 .cnb.yml 中，把 NPC 事件流水线挂在 $ 下（对所有角色生效）或角色名下（仅对指定角色生效）。

最小示例

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

NPC 所属仓库的 .cnb.yml
$:
  issue.comment@npc:
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

镜像说明

最小示例中使用 cnbcool/default-npc:latest 作为运行环境。如果你已构建并推送了自定义 NPC 镜像，可使用变量引用：

image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest

配置合并机制

NPC 事件触发时，系统通过 include 自动合并系统默认配置和 NPC 仓库的 .cnb.yml。NPC 仓库中已定义的事件覆盖默认，未定义的事件保留默认行为。

注意

合并按事件独立进行。若只配了 issue.comment@npc 而未配 pull_request.comment@npc，则 Issue 评论执行自定义流水线，PR 评论仍走默认。建议同时配置两个事件。

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

$:
  issue.comment@npc: # 来自 NPC 仓库（覆盖默认）
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

  pull_request.comment@npc: # 来自系统默认（保留）
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

完整示例

相比最小示例，完整示例使用自己构建并推送的 NPC 镜像 （通过 ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest 引用），并把镜像构建流水线也放进同一 .cnb.yml。

NPC 事件流水线（定义 NPC 被 @ 时的行为）：

NPC 所属仓库的 .cnb.yml（NPC 事件部分）
$:
  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

Docker 镜像构建流水线（在 push 事件上构建并推送镜像到制品库，供上面的 NPC 事件流水线使用）：

NPC 所属仓库的 .cnb.yml（镜像构建部分）
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

以上两部分可合并放在同一 .cnb.yml 文件中。镜像本身如何构建见后面的自定义运行环境。

按角色名配置

如果一个仓库里定义了多个 NPC 角色，希望它们各自跑不同的流水线，可以把事件挂在角色名顶层 key 下（与 $ 平级）。当被 @ 的角色名与某顶层 key 一致时，才会加载对应的自定义流水线。

未在 .cnb.yml 中显式配置 NPC 事件时，系统会使用内置的默认配置。下例中，专家 角色被 @ 时执行 专家: 下的自定义流水线；其他角色（未匹配到任何顶层 key）走系统默认行为。

NPC 所属仓库的 .cnb.yml
# 仅对「专家」角色覆盖事件流水线
专家:
  # Issue 评论与 PR 评论事件配置一致，可按需配置
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

与 $ 下配置的合并关系：

如果仓库中同时存在 $ 顶层 key（即所有角色共用的默认配置），匹配到角色名顶层 key 时，会按 include 语义与默认配置（系统默认 + $ 下配置）合并； 角色名下的同名事件会覆盖 $ 下的同名事件，未在该 key 下定义的事件仍走系统默认行为。

命名要求

顶层 key 必须与 .cnb/settings.yml 中 npc.roles[].name 完全一致（区分大小写、字符精确匹配）。
顶层 key 不要带 @ 前缀、也不要带括号中的角色名，例如不要写 @cnb/feedback(专家)。
同一仓库下可以为不同角色各自定义独立的顶层 key，互不覆盖。

自定义运行环境

npc:go 任务运行在 NPC 事件流水线的 Docker 容器中。运行环境（即用哪个镜像）有三种选择，按需求由简到繁：

默认：不做任何配置，系统使用 cnbcool/default-npc:latest。
直接指定已有镜像：在 .cnb.yml 的 docker.image 中填一个现成镜像地址，跳过自己构建的步骤。
构建自定义镜像：编写 Dockerfile，用一条流水线把镜像构建并推送到制品库，再在 NPC 事件流水线的 docker.image 中引用它。

注意：Dockerfile 不会被 NPC 直接读取运行，它只用于构建镜像。完整流程见上面的完整示例：Dockerfile → push 事件构建镜像 → NPC 事件引用镜像。

自定义镜像的 Dockerfile 示例

构建自定义 NPC 镜像时，Dockerfile 里通常需要安装 NPC 运行时依赖的 Skills 和 CLI 工具。下面的示例安装了 cnb-cli 和 skills 命令行，并预装了官方 cnb-skill：

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 加载目录

Skills 会自动加载以下目录：

用户级：~/.agents/skills、~/.codebuddy/skills
项目级：.agents/skills、.codebuddy/skills

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

分享 NPC

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

他们怎么找到你的 NPC？ 只要 NPC 所属仓库是公开的，或者对方拥有该仓库的读权限，就能在评论编辑器中输入完整 NPC 路径 @仓库路径(角色名) 直接提及。路径格式参考上文两类 NPC。

如何让 NPC 出现在选择器里？ 当其他人关注了 NPC 所属仓库后，你定义的 NPC 会自动出现在对方的 @ 选择器中，无需记路径。详见上文 NPC 选择器。

NPC