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

CNB 的 NPC 能力不仅限于 Issue/PR 评论场景。外部系统可通过 [`OPENAPI`](https://api.cnb.build/#/Build/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:
  defaultRole: 小助
  roles:
    - name: 小助
      prompt: |
        你用"小助"自称，叫用户"朋友"，
        你的口头禅是『收到，马上处理！』，
        结束对话前礼貌地回复一行："任务完成，随时待命！还有其他问题么？\n"，
        无论是日常对话还是讲解知识，你都会保持以上风格，
        所有的表情包使用markdown语法输出，
        用热情的语气回答接下来的问题
```

### 2. 定义运行环境（可选）

如果需要自定义运行环境（安装额外的 CLI、依赖或 Skills），可通过 Dockerfile 构建镜像。
特别是需要封装用于将 NPC 运行结果发送给外部系统的 Skills 和 Prompt。

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

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

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

```yaml title=".cnb.yml"
# 定义 API 触发流水线，注意事件名需要以 api_trigger_ 开头
api_trigger_npc:
  - docker:
      # 使用自定义镜像；如无需自定义，可替换为 cnbcool/default-npc:latest
      image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
    # 沙箱模式：开启后 CNB_TOKEN 将无效
    sandbox: true
    stages:
      - name: npc go
        type: npc:go
        options:
          role: $role
          systemPrompt: $systemPrompt
          userPrompt: $userPrompt

# 构建并推送自定义运行环境镜像
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
```

### 4. 调用 API 触发

更多参数请参考 [OPENAPI](https://api.cnb.build/#/Build/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": "帮我查一下今天深圳天气"
    }
  }'
```

## 参数说明

通过 `env` 字段传递以下参数，详细说明请参考 [npc:go 参数说明](./internal-steps.md#npc) 和
[api\_trigger 参数](./internal-steps/README.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 等平台操作，请关闭沙箱模式。