跳到主要内容

造一个你自己的 NPC

系统的 @CodeBuddy 好用，但角色人设、运行环境、行为流程都是别人的。想要专属的，三步就能做。

一、第一步：定义角色（必须做）​

在仓库 .cnb/settings.yml 里加：

.cnb/settings.yml
npc:
  roles:
    - name: 专家
      slogan: 专业解答，高效协助
      prompt: |
        你以"专家"自称，致力于提供专业、准确的技术解答。
        回复时保持简洁专业，引用可靠来源。

配置完就能用 @<你的仓库路径>(专家) 提及。

只做这一步就够用——系统会用默认运行环境 cnbcool/default-npc:latest 兜底，不需要写 .cnb.yml 也不要 Dockerfile。

角色配置项：

参数说明
name角色名，@ 时用
slogan标语，展示在 NPC 卡片
prompt系统提示词，决定人设与风格
enableThinking是否开思考模式，默认 true
avatar.src头像，仅支持默认分支中的图片

还能引入其他仓库的知识库，并配一个入口按钮：

.cnb/settings.yml
npc:
  imports:
    list:
      - cnb/docs
  roles:
    - name: 审查员
      prompt: 你是一名代码审查员，专注于代码质量把控和改进建议
  defaultRepo: cnb/docs
  defaultRole: 审查员
  button:
    name: 快速问AI
    description: 点火，启动 AI!
    hoverImage: .cnb/knowledge-base-hover.png

二、第二步：自定义行为（可选）​

默认行为就是"跑 npc:go，执行任务，回复评论"。要改流程就写 .cnb.yml：

.cnb.yml
$:
  issue.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

  pull_request.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

一个仓库多个角色，各跑不同流程——把事件挂在角色名顶层 key 下（与 $ 平级）：

.cnb.yml
专家:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

:::warning 命名必须完全一致 顶层 key 必须和 .cnb/settings.yml 里 npc.roles[].name 逐字符一致（区分大小写）。 不要带 @ 前缀，也不要带括号。 :::

角色名下的同名事件会覆盖 $ 下的，没定义的事件仍走系统默认。

三、第三步：自定义运行环境（可选）​

想预装 CLI、语言运行环境、Skills，就自己建镜像。

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

再配一条流水线把镜像推到制品库：

.cnb.yml
main:
  push:
    - services:
        - docker
      stages:
        - name: build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

然后在 NPC 事件里引用它。

:::tip Skills 加载顺序 全局级 ~/.agents/skills、~/.codebuddy/skills 优先于项目级 .agents/skills、.codebuddy/skills。 同名 Skill 全局覆盖项目级——这是为了防止仓库里过时的旧副本顶掉镜像里的新版。 :::

四、推荐做法：一步步验证​

每完成一步，就去 Issue 评论里 @ 一次验证效果，别一口气配到底。出问题时好定位是哪一层的问题。

顺序：定义角色 → 验证 → 自定义行为 → 验证 → 自定义环境 → 验证。

五、更狠的用法：从外部系统调 NPC​

不只是评论能召唤 NPC。任何系统都能通过 OpenAPI 触发：

curl --request POST \
  --url 'https://api.cnb.cool/<组织>/<仓库>/-/build/start' \
  --header 'Authorization: <你的令牌>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event": "api_trigger_npc",
    "env": {
      "role": "小助",
      "systemPrompt": "你是一个自动化助手，负责执行用户指定的任务",
      "userPrompt": "帮我查一下今天的构建失败原因"
    }
  }'

对应的流水线：

.cnb.yml
main:
  api_trigger_npc:
    - docker:
        image: cnbcool/default-npc:latest
      sandbox: true
      stages:
        - name: npc go
          type: npc:go
          options:
            role: $role
            systemPrompt: $systemPrompt
            userPrompt: $userPrompt

三个关键点：

  1. 事件名必须以 api_trigger_ 开头
  2. systemPrompt 和 userPrompt 必填——API 触发时提示词不会由角色自动带上，只配 role 会被拦下
  3. 沙箱模式（sandbox: true）会让 CNB_TOKEN 失效，无法操作平台资源。要提交代码、评论 Issue 就关掉

如果要让这次构建整体以 CodeBuddy 身份运行（评论显示为 @CodeBuddy、按 NPC 语义计费），传 npc 字段：

{
  "event": "api_trigger_npc",
  "npc": { "name": "CodeBuddy", "workMode": true },
  "env": { "systemPrompt": "...", "userPrompt": "..." }
}

npc.name 目前只接受 "CodeBuddy"；workMode: true 才会拿到写权限。