npc:go

3618 字约 12 分钟

npc:go

在流水线中执行 AI 任务，是 NPC 的运行入口。

使用场景：想让 AI 参与自动化流程时使用——例如在 Issue / PR 评论中 @NPC 让它回答问题、协作改代码，或由其他事件、api_trigger 触发，让 AI 自动处理构建产物、生成报告等。这类任务通常需要安装 CLI 与 Skills 并接入模型，直接写脚本成本较高，npc:go 把这一步收敛成一个内置任务。

NPC 运行在指定的 Docker 镜像中，因此可以在镜像里安装它所需的 CLI 工具和 Skills，例如使用 CNB Skill。

提示词从哪来：@NPC 评论触发时，平台自动拉起使用 npc:go 的流水线，提示词由 NPC 角色自带，无需配置；其他触发方式下提示词需自行配置，详见参数。更多 NPC 相关配置，请查阅自定义 NPC。

适用事件
参数
- 提示词配置
环境变量
超时
输出结果
配置样例

适用事件

所有事件

参数

参数速览

以下列表按用途列出 npc:go 的全部参数，方便先对整体有概念，再跳转到对应小节细看。

role：NPC 角色名，仅「自行提供提示词」场景生效
systemPrompt：NPC 系统提示词，「自行提供提示词」场景可选，不传自动采用 api_trigger 内置提示词
userPrompt：NPC 用户输入，「自行提供提示词」场景必填
model：Agent 使用的模型 ID，所有事件下生效
maxTurns：Agent 最大对话轮次，所有事件下生效
contextWindow：模型上下文窗口大小，所有事件下生效
maxTokens：模型最大输出 token 数，所有事件下生效
thinkingLevel：模型推理深度，所有事件下生效
supportImage：是否启用图片输入，所有事件下生效

提示词配置

role、systemPrompt、 userPrompt 三个参数都与提示词有关，但是否需要配置，取决于两个相互独立的维度，分别判断即可：

维度一：NPC 语义是怎么触发的

@NPC 评论触发（issue.comment@npc / pull_request.comment@npc）：以评论中的 @NPC 为入口，平台自动拉起流水线。
其他方式触发：push / crontab 等事件触发器、手动触发，以及在 api_trigger 的请求体中带上 npc.name=CodeBuddy（让本次构建以 NPC 身份运行）。

维度二：提示词由谁提供

NPC 角色自带：@NPC 评论触发时，平台按 .cnb/settings.yml 中的角色定义注入提示词，你无需配置，即使配了上述三个参数也会被忽略（角色定义优先级更高）。
自行提供：除上述场景外，提示词都要由你在 options 中给出：
- systemPrompt（可选）：系统提示词，不传时自动采用 api_trigger 的内置系统提示词；
- userPrompt（必填）：用户输入；
- role（可选）：按 .cnb/settings.yml 中的 NPC 角色解析，作为人格段拼接到 system prompt。

两个维度的关系：只有 @NPC 评论触发才由角色自带提示词，其余触发方式（包括带 npc.name 的 api_trigger）都需要自行提供。api_trigger 的 npc.name 只决定本次构建以哪个代理人身份运行（影响流水线展示、标题、计费口径、CNB_TOKEN 权限等），不提供提示词。

只配置 role 不能替代提示词

role 只把角色 prompt 作为人格段拼接，不提供系统提示词本身，也不提供用户输入。 systemPrompt 可以不传（自动采用 api_trigger 的内置系统提示词），但 userPrompt 缺失或为空仍会直接报错，只配置 role 也会被拦下：

.cnb.yml
$:
  # crontab 触发需要自行提供提示词
  crontab:
    - cron: "0 10 * * *"
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: 版本守卫
            # userPrompt 不能省略；systemPrompt 可选，不传时用内置提示词
            systemPrompt: 你是版本守卫，负责核对并更新仓库中的版本号。
            userPrompt: 检查并更新仓库版本号。

role

type: String
required: false

NPC 角色名称，需在 .cnb/settings.yml 文件的 NPC 的 roles 字段中定义，可参考 UI 定制。仅在自行提供提示词时生效；@NPC 评论触发（issue.comment@npc / pull_request.comment@npc）时由角色自带提示词，本参数被忽略。

systemPrompt

type: String
required: false

NPC 系统提示词，用于定义 NPC 的行为准则与任务边界。

自行提供提示词时可选，包括 push / crontab 等事件触发器、手动触发，以及带 npc.name 的 api_trigger；@NPC 评论触发时被忽略，提示词由 .cnb/settings.yml 中的 NPC 角色自带。

不传时自动采用 api_trigger 的内置系统提示词（NPC 基础准则 + 工具使用约定），并照常拼接 Skill、知识库、role 人格段与项目上下文，适合「任务本身在 userPrompt 里已说清、无需额外约束行为」的场景。

配置了 role 时也无需额外传 systemPrompt： role 解析出的角色 prompt 只作为人格段拼接，会叠加在内置提示词之上。

userPrompt

type: String
required: false

NPC 用户输入，主要用于用户向 NPC 描述任务。

自行提供提示词时必填（这是必填项，缺失或为空会直接报错）；@NPC 评论触发时被忽略，提示词由 NPC 角色自带。

maxTurns

type: Number
required: false

Agent 最大对话轮次。所有事件下均生效，达到上限时 Agent 会被中止，输出可能不完整。

不指定时取值规则：

未指定 model（使用平台默认模型）时，沿用平台为默认模型配置的 maxTurns；
指定了自定义 model 时，不再沿用平台为默认模型配置的取值，回落到内置默认 500。

显式传入时以你的取值为准。

model

type: String
required: false

Agent 使用的模型 ID。不指定时使用平台默认模型，所有事件下均生效。

contextWindow

type: String | Number
required: false

模型上下文窗口大小，支持以下写法：

带小写单位："128k"（k = 1000）或 "1m"（m = 1000000）
纯数字：128000 或 "128000"

取值范围为 128k ~ 1m（即 128000 ~ 1000000 tokens），越界或格式不合法（如大写、带小数、带空白）会直接报错。用于上下文超限时触发自动摘要压缩，需与所选 model 实际支持的上下文窗口保持一致。不指定时取值规则：

未指定 model（使用平台默认模型）时，沿用平台 CodeBuddy NPC 为默认模型配置的取值；
指定了自定义 model 时，不再继承 CodeBuddy NPC 的配置（上下文能力因模型而异、不可复用），回落到内置默认 1m（1000000）。

显式传入时以你的取值为准，所有事件下均生效。

示例：

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            contextWindow: 128k # 等效于 128000，也可写成 "128000" 或 128000

  # issue 评论与 PR 评论事件配置一致，可按需配置
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            contextWindow: 128k # 等效于 128000，也可写成 "128000" 或 128000

maxTokens

type: String | Number
required: false

模型最大输出 token 数，支持以下写法：

带小写单位："48k"（k = 1000）或 "1m"（m = 1000000）
纯数字：64000 或 "64000"

校验接受范围为 48k ~ 1m（即 48000 ~ 1000000 tokens），越界或格式不合法（如大写、带小数、带空白）会直接报错。不指定时取值规则：

未指定 model（使用平台默认模型）时，沿用平台 CodeBuddy NPC 为默认模型配置的取值；
指定了自定义 model 时，不再继承 CodeBuddy NPC 的配置（能力因模型而异、不可复用），回落到内置默认 48k（48000）。

显式传入时以你的取值为准，所有事件下均生效。

示例：

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            maxTokens: 64k # 等效于 64000，也可写成 "64000" 或 64000

  # issue 评论与 PR 评论事件配置一致，可按需配置
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            maxTokens: 64k # 等效于 64000，也可写成 "64000" 或 64000

thinkingLevel

type: String
required: false

模型推理深度，可选值：off / minimal / low / medium / high / xhigh / max。不指定时取值规则：

未指定 model（使用平台默认模型）时，沿用平台 CodeBuddy NPC 为默认模型配置的取值；
指定了自定义 model 时，不再继承 CodeBuddy NPC 的配置（推理能力因模型而异、不可复用），回落到内置默认 medium。

显式传入时以你的取值为准，所有事件下均生效。

示例：

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            thinkingLevel: high # 提高推理深度以获得更深入的思考，可选 off / low / medium / high / xhigh / max 等

  # issue 评论与 PR 评论事件配置一致，可按需配置
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            thinkingLevel: high # 提高推理深度以获得更深入的思考，可选 off / low / medium / high / xhigh / max 等

supportImage

type: Boolean
required: false

是否启用图片输入能力（多模态）。开启后，NPC 可读取并理解 Issue / PR 评论等场景中粘贴的图片（支持 PNG / JPEG / WebP / GIF）。

图片体积由 NPC 自动处理：读取时会先用容器内的 ffmpeg 把图片压缩到 512 KiB 以内（缩尺寸 + 转 JPEG；默认镜像已内置 ffmpeg，无需自行安装），压缩产物以 base64 内联给模型，原文件不会被修改。压缩后仍超过 1 MiB 内联上限时才会拒绝读取并给出缩图指引。

不指定时取值规则：

未指定 model（使用平台默认模型）时，沿用平台 CodeBuddy NPC 为默认模型配置的开关；
指定了自定义 model 时，不再继承 CodeBuddy NPC 的配置（不同模型的图片能力不可复用），回落到内置默认 false（关闭）。

显式传 true 才会注册图片读取工具并声明图片输入；设为 false 或未配置时，图片仅按纯文本处理。

示例：

.cnb.yml
$:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            supportImage: true # 启用图片输入（多模态）

  # issue 评论与 PR 评论事件配置一致，可按需配置
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            supportImage: true # 启用图片输入（多模态）

模型能力参数的默认值

model、maxTurns、 contextWindow、maxTokens、 thinkingLevel、supportImage 这几个参数都与所选模型相关：不同模型的能力（上下文窗口、最大输出、推理深度、图片输入）并不通用，因此它们的默认值并不是固定不变的。

无论配置哪个参数，取值都遵循同一条优先级规则：

显式指定 时，以你传入的值为准；
未指定 时，取决于是否指定了 model：
- 未指定 model（走平台默认模型）——沿用平台 CodeBuddy NPC 为默认模型配置的对应取值；
- 指定了自定义 model——不再沿用默认模型的配置，回落到下面的内置默认值。

maxTurns：500
contextWindow：1m（1000000）
maxTokens：48k（48000）
thinkingLevel：medium
supportImage：false（关闭）

未指定 model 时各参数沿用的默认模型配置值，以各参数小节说明为准。

环境变量

npc:go 会读取当前流水线的全部环境变量，包括平台内置变量、流水线 / Stage / Job 各层的 env 与 imports，以及上游 Job 的 exports。

超时

工具执行超时

Agent 会在会话中执行大量工具（如 bash 命令）。所在 Job 声明的 timeout 作用于 Agent 的每一次工具执行，而非整个 Agent 会话：

单次工具执行超过该时长、或连续无输出达到该时长，会被强制中断并以执行失败返回给 Agent；
未声明 timeout 时取默认值：无输出超时 10 分钟，单次工具执行最长 2 小时。

即：timeout 限制的是「单次工具执行」，会话中可以执行很多次工具，各自的时长分别受限。

Agent 会话本身不设整体超时，整体时长受流水线超时（20 小时）约束。

输出结果

{
  // NPC 最后一条 assistant 消息的文本内容
  "result": "..."
}

配置样例

1. NPC 事件流水线：在 issue.comment@npc 事件中调用 npc:go，镜像需包含 NPC 运行时需要的 CLI 工具和 Skills（镜像构建见下方第 2 步）：

.cnb.yml
$:
  issue.comment@npc:
    - docker:
        # 指定镜像，内含 NPC 运行时需要的 CLI 工具和 Skills
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

2. 构建并推送 NPC 镜像：将镜像推送到制品库后，供上方 NPC 事件流水线使用：

.cnb.yml
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 全局级会覆盖项目级。即仓库内自带同名 Skill 时，以镜像内安装的全局版本为准。

NPC 角色的 prompt 定义在 .cnb/settings.yml 文件中，请查阅自定义 NPC。