CNB 文档

简体中文

English

简体中文

English

外观

外部系统接入 NPC

复制页面

1499 字约 5 分钟

外部系统接入 NPC 介绍如何通过 API 触发 NPC 流水线执行自动化任务。

使用场景：想让自建系统也调用 CNB 的 AI 能力时使用——例如业务系统里一键召唤 NPC 处理需求、 按自己的角色、Skills 和 Prompt 定制 NPC，而无需在 Issue/PR 里评论。

概述

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

时序图如下：

配置步骤

1. 定义 NPC 角色

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

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

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

如需自定义运行环境（安装额外的 CLI、依赖或 Skills），可通过 Dockerfile 构建镜像。 Dockerfile 内容与 NPC 自定义运行环境 相同。

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

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

.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：

.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。 触发后可以在 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": "帮我查一下今天深圳天气"
    }
  }'

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

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

沙箱模式

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

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

© 2026 cnb.cool