5703 字约 19 分钟
云原生构建里的 NPC(Non-Player Character) 是一类自动化角色:在 Issue 或 PR 的评论里 @ 一个 NPC 并描述需求,平台就会为它启动一条流水线,让它替你回复、协作代码,甚至闭环解决 Issue。 NPC 既有开箱即用的系统 NPC,也有你在仓库里定义的自定义 NPC。 本文介绍 NPC 的使用方法、触发事件、工作模式与安全限制,以及如何定义和定制自己的 NPC。
快速上手
在 Issue 或 PR 的评论中 @CodeBuddy 并说出需求,它会自动执行并回复:
@CodeBuddy 帮我实现这个 Issue
@CodeBuddy 帮我审查一下这个 PR 的代码@CodeBuddy 是系统内置 NPC,开箱即用。
定义自己的 NPC
在仓库 .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):当事人授予代理人的权限范围,受三重约束:
- 限时:仅本次任务有效。
- 限地:仅限当前仓库。
- 限权:角色上限为开发者(
Developer)。
任务结束或流水线销毁时自动终止。
NPC 能力
NPC 能做的事分为三层,由浅入深:
- 自动回复:回答评论区问题、给出代码审查意见等文字回复
- 工作模式:开启后 NPC 可自主写代码、推代码、建分支、发 PR、按评审意见修改,闭环解决 Issue
- 自定义行为:定义 NPC 的角色人设与运行方式
读取并分析图片
在 Issue 或 PR 的讨论里,你可以直接粘贴图片(如错误截图、界面截图、流程图), 并在同一段文字里要求 NPC 查看并分析这些图片,让 NPC 结合文字完成分析、定位问题。
NPC 是否支持读取图片,由平台配置 + 模型能力共同决定:
- 平台可在
NPC_CONFIG中声明supportImage: true,作为默认模型的基础图片能力。 - 同时要求 NPC 所采用的底层模型支持图片输入,两者都满足时 NPC 才会真正 读取并理解图片内容。
除平台配置外,你也可以在自己流水线的 npc:go options 中通过 supportImage 字段开启或关闭图片输入:
- 未指定该字段时,默认值按以下规则决定:
npc:go中未指定model(走平台默认模型)时,继承平台NPC_CONFIG为默认模型配置的supportImage;npc:go中指定了model(自定义模型)时,不继承平台为默认模型配置的supportImage,回落到内置默认false——不同模型的图片能力并不通用, 以免把针对默认模型开启的开关套用到自定义模型上。
- 显式传
supportImage: true时才会声明图片输入并注入读图能力。
说明
- 图片支持 PNG / JPEG / WebP / GIF。超限图片会自动用容器内的
ffmpeg压缩到 512 KiB 以内再送给模型(原文件不改动),直接粘贴大截图也可以。 - 若能力未开启或模型不支持图片输入,读取图片只会返回路径、类型与大小等元信息, 无法识别图片内容,这种情况下改用文字描述问题即可。
两类 NPC
云原生构建里有两类 NPC:
- 系统 NPC——平台内置,目前是
CodeBuddy,通过@CodeBuddy直接使用。 - 自定义 NPC——用户在自己的仓库中定义的角色,通过
@仓库路径(角色名)提及:
@<你的仓库路径>(专家) 帮我回答下这个 issue。@ 后是 NPC 所属仓库路径(如 your-group/your-repo), 括号里是角色名(如 专家),两者共同定位到一个具体的 NPC。
工作模式
默认情况下,NPC 只能读代码、写评论。要让它完成开发闭环(写代码、推代码、发 PR), 在评论编辑器右上角打开 「替我上班」 开关即可开启工作模式,授予更高权限。 把鼠标悬停在开关上,可查看开启后获得的权限说明。

开启工作模式需要仓库 开发者及以上 权限。开启后,NPC 可自主:
- 编写代码、推送代码、创建分支
- 创建合并请求(PR)
- 按 PR 评审意见修改代码
- 协助解决 Issue
详细令牌权限说明见 CNB_TOKEN。
NPC 选择器
在评论编辑器中输入 @ 即可弹出 NPC 选择器, 其中列出了系统 NPC、你定义的 NPC,以及你关注仓库中的 NPC,点选即可提及。
NPC 全景流程图
一图串起上面的概念:谁发起、触发了什么、在哪执行、能做什么,以及哪些环节可以定制。 图中 🔧 标记即为你可定制的部分,虚线指向该定制项起作用的环节。
读图要点:
- 入口只有
@,但两条路径不同:系统 NPC 开箱即用,自定义 NPC 先在.cnb/settings.yml里定义角色。 - 工作模式决定权限上限,
Reporter/Guest无法开启。 - NPC 类型与工作模式互不影响,系统 NPC 和自定义 NPC 都能开关工作模式。
- 系统默认已经够用,只有需要改动时,才在 NPC 仓库的
.cnb.yml里覆盖。 - 可定制从浅到深:角色 → 事件行为 → 运行环境 → 任务参数 → 权限边界,每加一层都要重新
@验证。
NPC 事件
@ 提及 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 为例):
- 当前评论下方显示被提及的 NPC 角色名及流水线执行状态
- 若 NPC 使用 CNB_TOKEN 回复了评论, 评论提交者显示为 NPC 角色名
- 计费口径:NPC 视作开发场景,消耗云原生开发用量。

安全限制
以下限制是 委托代理模型中限地与限权约束的具体体现:
- 仓库范围:NPC 事件流水线中
CNB_TOKEN默认仅限访问当前仓库。 跨仓 Fork PR 的pull_request.comment@npc事件中, 若触发者为 PR 提交者,CNB_TOKEN仅限访问公开仓库。 - 角色上限:
CNB_TOKEN的最大角色取决于触发用户在仓库中的角色:Developer/Master/Owner→ 最大角色DeveloperReporter/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 列表定义一个或多个角色:
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 事件的流水线:
$:
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 被 @ 时的行为):
$:
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:goDocker 镜像构建流水线(在 push 事件上构建并推送镜像到制品库,供上面的 NPC 事件流水线使用):
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)走系统默认行为。
# 仅对「专家」角色覆盖事件流水线
专家:
# 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:
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 -ySkills 加载目录
Skills 会自动加载以下目录:
- 全局级:
~/.agents/skills、~/.codebuddy/skills - 项目级:
.agents/skills、.codebuddy/skills
同名 Skill 全局级优先,会覆盖项目级: 项目仓库里自带一份同名 Skill 时,以镜像内安装的全局版本为准, 避免仓库内未及时更新的旧副本(如旧版 cnb-skill)顶掉全局版本。
分享 NPC
定义了好用的 NPC 后,怎样让其他人也能用上?
他们怎么找到你的 NPC? 只要 NPC 所属仓库是公开的,或对方拥有该仓库的读权限, 就能在评论编辑器中输入完整路径 @仓库路径(角色名) 直接提及,格式见上文 两类 NPC。
如何让 NPC 出现在选择器里? 对方关注 NPC 所属仓库后,你定义的 NPC 会自动出现在他的 @ 选择器中,无需记路径。 详见上文 NPC 选择器。
更多使用场景
前面讲的都是 @ 触发的场景,但 NPC 的核心是 AI 驱动的自动化任务,@ 只是入口之一。 在任意事件的流水线里,都可以用内置任务 npc:go 把 NPC 能力用起来。 与 @ 触发不同,这些场景提示词不会被角色自动带上,需要在 options 中自行配置 (详见 npc:go 提示词配置)。
下面两个示例都不是 NPC 事件,代码写权限按流水线 CNB_TOKEN 的权限来定,和
@触发的规则不同。
示例 1:PR 自动审查
场景:不想每次手动 @CodeBuddy 审 PR,希望一开 PR 就自动跑一次 AI 审查。
$:
pull_request:
- docker:
image: cnbcool/default-npc:latest
stages:
- name: npc go
type: npc:go
options:
role: 代码审查员
systemPrompt: 你是一个专业的代码审查员,请审查代码变更并给出改进建议
userPrompt: 审查本次 PR 的代码变更,给出改进建议示例 2:网页按钮手动触发
场景:在仓库主页放一个按钮,点击后弹窗输入任务描述并交给 NPC 执行—— 用户既不用写评论,也不用懂流水线。
$:
web_trigger:
- docker:
image: cnbcool/default-npc:latest
stages:
- name: npc go
type: npc:go
options:
role: 小助
systemPrompt: 你是一个助手,负责执行用户指定的任务并回复结果
userPrompt: $userPrompt其中 $userPrompt 读取用户在页面上填写的 userPrompt 输入框, 按钮的配置方式参考 手动触发流水线。
其他触发入口
@ 评论和流水线事件之外,还有两个入口能把 NPC 用起来。 共同点是提示词不由角色提供,都要在 options 里自己写。
- 调 OpenAPI 触发构建:触发
api_trigger时传入npc.name=CodeBuddy,该次构建就按 NPC 语义处理——操作者展示为 NPC 身份而非调用 API 的用户, 构建标题按 NPC 语义生成,计费归入 NPC 场景,Token 资源限定也按 NPC 规则收窄。 这条路径下npc:go的systemPrompt/userPrompt仍从流水线options里读, 其中userPrompt必填,只配role会被拦下。 - 外部系统接入:想让自己的平台(如客服系统、内部工作台)也能召唤 NPC 干活, 同样通过 API 触发流水线实现,完整方案见 外部系统接入 NPC。
两个入口的参数细节见 npc:go 参数说明: 提示词不由 NPC 角色提供,npc:go 从流水线 options 中读取,userPrompt 必填、 systemPrompt 可选(不传时使用内置系统提示词),role 只把角色设定拼进系统提示词, 不能替代 userPrompt。API 触发下这些参数没配全,构建会直接失败。