---
url: /zh/build/internal-steps/npc/go.md
---
`npc:go`

在指定的 Docker 镜像中执行 AI 任务。

在 Issue 或 PR 评论中 @NPC 角色会使用内置的 system/user prompt；
其他事件下，可通过 `systemPrompt`、`userPrompt`、`role` 参数自定义提示词。

可以在镜像中安装 NPC 运行时所需的 CLI 工具和 Skills，
例如使用 [CNB Skill](https://cnb.cool/cnb/skills/cnb-skill)。
更多 NPC 相关配置，请查阅
[自定义 NPC](../../npc.md)。

* [适用事件](#npc-go-applicable-events)
* [参数](#npc-go-parameters)
* [环境变量](#npc-go-environment)
* [超时](#npc-go-timeout)
* [输出结果](#npc-go-output)
* [配置样例](#npc-go-configuration-examples)

## 适用事件 {#npc-go-applicable-events}

[所有事件](../../trigger-rule.md#trigger-event)

## 参数 {#npc-go-parameters}

### 参数速览

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

* [role](#npc-go-parameters-role)：NPC 角色名，仅 API 触发时生效
* [systemPrompt](#npc-go-parameters-systemPrompt)：NPC 系统提示词，仅 API 触发时生效
* [userPrompt](#npc-go-parameters-userPrompt)：NPC 用户输入，仅 API 触发时生效
* [model](#npc-go-parameters-model)：Agent 使用的模型 ID，所有事件下生效
* [maxTurns](#npc-go-parameters-maxTurns)：Agent 最大对话轮次，所有事件下生效
* [contextWindow](#npc-go-parameters-contextWindow)：模型上下文窗口大小，所有事件下生效
* [maxTokens](#npc-go-parameters-maxTokens)：模型最大输出 token 数，所有事件下生效
* [thinkingLevel](#npc-go-parameters-thinkingLevel)：模型推理深度，所有事件下生效
* [supportImage](#npc-go-parameters-supportImage)：是否启用图片输入，所有事件下生效

`role`、`systemPrompt`、`userPrompt` 用于定制 NPC 的提示词，是否需要配置取决于触发方式：

* **评论触发**（在 Issue / PR 评论中 `@NPC`，即 `issue.comment@npc` /
  `pull_request.comment@npc` 事件）：提示词已由 NPC 角色自带，**无需配置**。
  角色及其提示词在 `.cnb/settings.yml` 中定义、优先级更高，即使在本步骤配置了
  `role`、`systemPrompt`、`userPrompt` 也会被忽略。
* **API 触发**（[`api_trigger`](../../trigger-rule.md#api_trigger)）：需要**自行配置**提示词。
  请求体中的 `npc.name=CodeBuddy` 只会让本次构建以 `@CodeBuddy` 为代理人运行
  （影响流水线展示、标题、计费口径、CNB\_TOKEN 权限等），提示词仍需由你提供：
  * `systemPrompt` / `userPrompt`：在本步骤的 `options` 中传入；
  * `role`（可选）：配置后按 `.cnb/settings.yml` 中的 NPC 角色解析，拼接到
    system prompt。

### role {#npc-go-parameters-role}

* type: `String`
* required: `false`

NPC 角色名称，需在 `.cnb/settings.yml` 文件的 NPC 的 roles 字段中定义，
可参考 [UI 定制](../../../repo/settings.md)。
仅 API 触发（`api_trigger`）时生效；评论触发（`issue.comment@npc` / `pull_request.comment@npc`）时被忽略。

### systemPrompt {#npc-go-parameters-systemPrompt}

* type: `String`
* required: `false`

NPC 系统提示词。
仅 API 触发（`api_trigger`）时必填；评论触发（`issue.comment@npc` / `pull_request.comment@npc`）时被忽略，
提示词由 NPC 角色自带。

### userPrompt {#npc-go-parameters-userPrompt}

* type: `String`
* required: `false`

NPC 用户输入，主要用于用户向 NPC 描述任务。
仅 API 触发（`api_trigger`）时必填；评论触发（`issue.comment@npc` / `pull_request.comment@npc`）时被忽略，
提示词由 NPC 角色自带。

### maxTurns {#npc-go-parameters-maxTurns}

* type: `Number`
* required: `false`

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

不指定时取值规则：

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

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

### model {#npc-go-parameters-model}

* type: `String`
* required: `false`

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

### contextWindow {#npc-go-parameters-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）。

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

示例：

```yaml title=".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 {#npc-go-parameters-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）。

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

示例：

```yaml title=".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 {#npc-go-parameters-thinkingLevel}

* type: `String`
* required: `false`

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

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

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

示例：

```yaml title=".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 {#npc-go-parameters-supportImage}

* type: `Boolean`
* required: `false`

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

不指定时取值规则：

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

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

示例：

```yaml title=".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`](#npc-go-parameters-model)、[`maxTurns`](#npc-go-parameters-maxTurns)、
[`contextWindow`](#npc-go-parameters-contextWindow)、[`maxTokens`](#npc-go-parameters-maxTokens)、
[`thinkingLevel`](#npc-go-parameters-thinkingLevel)、[`supportImage`](#npc-go-parameters-supportImage)
这几个参数都与**所选模型**相关：不同模型的能力（上下文窗口、最大输出、推理深度、图片输入）并不通用，
因此它们的默认值并不是固定不变的。

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

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

* [maxTurns](#npc-go-parameters-maxTurns)：`500`
* [contextWindow](#npc-go-parameters-contextWindow)：`1m`（1000000）
* [maxTokens](#npc-go-parameters-maxTokens)：`48k`（48000）
* [thinkingLevel](#npc-go-parameters-thinkingLevel)：`medium`
* [supportImage](#npc-go-parameters-supportImage)：`false`（关闭）

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

## 环境变量 {#npc-go-environment}

`npc:go` 会读取当前流水线的全部环境变量，包括平台内置变量、流水线 / Stage / Job 各层的
`env` 与 [`imports`](../../grammar.md#job-imports)，以及上游 Job 的 [`exports`](../../grammar.md#job-exports)。

## 超时 {#npc-go-timeout}

所在 Job 声明的 [`timeout`](../../timeout.md#任务超时) 作用于 Agent 的**每一次工具执行**（如 bash 命令）：
单次工具执行超过该时长、或连续无输出达到该时长，会被强制中断并以执行失败返回给 Agent；
未声明时取默认值（无输出超时 10 分钟，单次最长 2 小时）。

Agent 会话本身不设整体超时，整体时长受[流水线超时](../../timeout.md#流水线超时)（20 小时）约束。

## 输出结果 {#npc-go-output}

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

## 配置样例 {#npc-go-configuration-examples}

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

```yaml title=".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 事件流水线使用：

```yaml title=".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 title="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 角色的 prompt 定义在 `.cnb/settings.yml` 文件中，请查阅 [自定义 NPC](../../npc.md)。