Overview

CNB's NPC capabilities are not limited to Issue/PR comment scenarios. External systems can trigger pipelines via OPENAPI(Open in new window), customizing the NPC's role, runtime environment, Skills, Prompt, etc., to run automated tasks in a sandbox environment.

The sequence diagram is as follows:

Configuration Steps

1. Define NPC Role

Define the NPC role in the repository's .cnb/settings.yml file, including tone, style, etc.

.cnb/settings.yml

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

2. Define Runtime Environment (Optional)

If you need a custom runtime environment (additional CLI, dependencies, or Skills), build an image via Dockerfile. In particular, include the Skills and Prompts for sending NPC execution results to the external system.

If customization is not needed, skip this step and use the default NPC capability image cnbcool/default-npc:latest directly.

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. Define API Trigger Pipeline

.cnb.yml

# Define API trigger pipeline. Note: event name must start with api_trigger_
api_trigger_npc:
  - docker:
      # Custom image; replace with cnbcool/default-npc:latest if no customization needed
      image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest
    # Sandbox mode: when enabled, CNB_TOKEN will be invalid
    sandbox: true
    stages:
      - name: npc go
        type: npc:go
        options:
          role: $role
          systemPrompt: $systemPrompt
          userPrompt: $userPrompt

# Build and push custom runtime image
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. Call API to Trigger

For more parameters, see OPENAPI(Open in new window). After triggering, the corresponding pipeline can be viewed in the CNB Cloud Native Build pipeline list along with its execution status.

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": "Role name",
      "systemPrompt": "You are an automation assistant that executes user-specified tasks and sends results to the user via a WeCom bot. The bot webhook URL is...",
      "userPrompt": "Help me check today'\''s weather in Shenzhen"
    }
  }'

Parameter Description

Pass the following parameters via the env field. For detailed descriptions, see npc:go Parameter Description and api_trigger Parameters.

• role (String, Optional): NPC role name, defining tone and style. Must be defined in npc.roles of the repository's .cnb/settings.yml, e.g., 小助
• systemPrompt (String, Required): System prompt defining NPC behavior guidelines, including how to process userPrompt and how to send results to the external system.
• userPrompt (String, Required): User input, used to describe specific tasks to the NPC, e.g., Help me check today's weather in Shenzhen

Sandbox Mode

When sandbox mode is enabled, the NPC runs in an isolated secure environment. CNB_TOKEN in the pipeline will be invalid, preventing API calls and platform operations (such as committing code or commenting on Issues).

If the NPC needs to perform platform operations such as committing code or commenting on Issues, disable sandbox mode.