CNB 文档

简体中文

English

简体中文

English

外观

外部系统接入 NPC

复制页面

999 字约 3 分钟

概述

CNB 的 NPC 能力不仅限于 Issue/PR 评论场景。外部系统可通过 OPENAPI 触发流水线， 自定义 NPC 的角色、运行环境、Skills、Prompt 等，在沙箱环境中运行自动化任务。

时序图如下：

配置步骤

1. 定义 NPC 角色

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

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

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

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

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

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 触发流水线

.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。触发后可以在 CNB 云原生构建的流水线列表中看到对应的流水线，并查看执行情况。

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 参数说明 和 api_trigger 参数。

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

沙箱模式

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

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

© 2026 cnb.cool