---
url: /zh/build/npc-integration.md
description: |
  介绍外部系统如何通过 API 触发 CNB NPC 流水线， 实现自定义角色、运行环境、Skills 和 Prompt 的自动化任务。
---
## 概述

CNB 的 NPC 能力不局限于 Issue/PR 评论场景。
外部系统可通过 [`OPENAPI`](https://api.cnbprod.alpha.qq.com/#/operations/StartBuild) 触发流水线，
自定义 NPC 的角色、运行环境、Skills、Prompt 等，在沙箱环境中执行自动化任务。

时序图如下：

```mermaid
sequenceDiagram
    participant External as 外部系统
    participant API as CNB API
    participant Pipeline as 流水线
    participant NPC as npc:go
    participant Skills as Skills 能力

    External->>API: POST /{repo}/-/build/start
    API->>Pipeline: 触发流水线
    Pipeline->>NPC: 执行 npc:go<br/>读取 options 参数
    NPC->>NPC: 解析 .cnb/settings.yml<br/>匹配 role 角色
    NPC->>NPC: 构建 system prompt<br/>+ 角色设定 + skills
    NPC->>Skills: 根据任务加载 skill
    Skills-->>NPC: skill 指令
    NPC->>External: 通过 skill 回调外部系统
    External-->>NPC: 返回结果
    NPC-->>Pipeline: 任务完成
```

## 配置步骤

### 1. 定义 NPC 角色

在仓库的 `.cnb/settings.yml` 文件中定义 NPC 角色，包括语气、风格等。

```yaml title=".cnb/settings.yml"
npc:
  roles:
    - name: 小助
      prompt: |
        你用"小助"自称，叫用户"朋友"，
        你的口头禅是『收到，马上处理！』，
        结束对话前礼貌地回复一行："任务完成，随时待命！还有其他问题么？\n"，
        无论是日常对话还是讲解知识，你都会保持以上风格，
        所有的表情包使用markdown语法输出，
        用热情的语气回答接下来的问题
```

### 2. 构建自定义镜像（可选）

如需自定义运行环境（安装额外的 CLI、依赖或 Skills），可通过 Dockerfile 构建镜像。
Dockerfile 内容与 [NPC 自定义运行环境](../build/npc.md#自定义运行环境) 相同。

如果不需要自定义，可跳过此步骤，直接使用默认 NPC 能力镜像 `cnbcool/default-npc:latest`。

自定义镜像构建完成后，通过以下流水线推送到 CNB 制品库（复用仓库名作为镜像名）：

```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
```

### 3. 定义 API 触发流水线

在 `.cnb.yml` 的对应分支（默认 `main`）下定义 API 触发流水线，事件名需以 `api_trigger_` 开头。
使用之前推送的镜像或默认镜像 `cnbcool/default-npc:latest`：

```yaml title=".cnb.yml"
main:
  api_trigger_npc:
    - docker:
        # 使用步骤 2 构建的自定义镜像，或替换为 cnbcool/default-npc:latest
        image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
      sandbox: true
      stages:
        - name: npc go
          type: npc:go
          options:
            role: $role
            systemPrompt: $systemPrompt
            userPrompt: $userPrompt
```

### 4. 调用 API 触发

更多参数请参考 [OPENAPI](https://api.cnbprod.alpha.qq.com/#/operations/StartBuild)。
触发后可以在 CNB 云原生构建的流水线列表中看到对应的流水线，
并查看执行情况。

```bash
# 基础调用
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": "帮我查一下今天深圳天气"
    }
  }'

# 以 NPC 代理人身份触发（可选）：传入 npc 字段，"workMode": true 开启工作模式
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",
    "npc": {
      "name": "CodeBuddy",
      "workMode": true
    },
    "env": {
      "systemPrompt": "你是一个自动化助手...",
      "userPrompt": "帮我把这个分支合并到 main"
    }
  }'
```

调用 API 触发构建时，可以额外传入 `npc` 字段，
把整条流水线的运行身份切换为 NPC 代理人。
目前仅支持系统 NPC `@CodeBuddy`。此时：

* 主 `CNB_TOKEN` 自动携带 CodeBuddy 标识，平台操作 Issue / PR 等
  都会显示为 `@CodeBuddy` 自动化执行（与代码评论中触发 `@CodeBuddy` 一致）
* 在标题、计费口径、token 资源限定等维度，本次构建按「NPC 事件」语义处理

参数：

* **`npc.name`**（String，必填）：仅支持 `"CodeBuddy"`，其他取值会被 400 拒绝
* **`npc.workMode`**（Boolean，选填，默认 `false`）：
  控制 token 的 scope（权限范围）。CNB\_TOKEN 实际拿到的 scope 取决于本字段：

  * **`npc.workMode`** 为 `false` / 未传时，CNB\_TOKEN 的 scope 与原生"非工作模式
    NPC 事件"一致，以只读权限为主，适用于仅需读取仓库代码、写评论等场景。
  * **`npc.workMode`** 为 `true` 时，使用 NPC 工作模式 scope，适用于需要 `git push`、改 issue/PR 等写权限的自动化场景。

  注意：

  * 不传 `npc` 字段时，`api_trigger` 默认拿「可信事件 scope」（`TOKEN_SCOPE_CREDIBLE`，写权限较宽）。
    一旦传入 `npc=@CodeBuddy`，无论 `workMode` 是否为 `true`，
    scope **都不会**比同当事人生成的原生 NPC 事件更宽。
  * NPC 工作模式 scope 是可信事件 scope 的真子集（少了 `repo-manage:r`、`group-resource:r` 两个只读权限），
    不会放大权限。

## 参数说明

通过 `env` 字段传递以下参数，详细说明请参考 [npc:go 参数说明](./internal-steps/npc/go.md) 和
[api\_trigger 参数](./internal-steps/npc/go.md#npc-go-parameters)。

* **`role`**（String，选填）：NPC 角色名称，定义语气、风格，
  需在仓库 `.cnb/settings.yml` 的 `npc.roles` 中定义，例如 `小助`
* **`systemPrompt`**（String，必填）：系统提示词，
  用于定义 NPC 的行为指引，包括如何处理 `userPrompt`、
  如何将结果发送给外部系统等
* **`userPrompt`**（String，必填）：用户输入，
  用于向 NPC 描述具体任务，例如 `帮我查一下今天深圳天气`

## 沙箱模式

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

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