第 36 节 · CNB Pipeline + NPC 配置

一句话回答

两个配置文件把"评论 @ → 自动回复"串起来。 .cnb/settings.yml 定义 NPC 角色，.cnb.yml 定义 NPC 事件来时跑哪个镜像、执行什么流程。

完整链路回顾

评论 @owner/repo(my-agent) 帮我看看 bug
         ↓
CNB 检测到 NPC 被 @ → 触发 issue.comment@npc / pull_request.comment@npc
         ↓
流水线启动 Docker 容器（你的 NPC 镜像）
         ↓
容器里 npc-entrypoint 读 CNB 环境变量、调 my-agent --solo exec
         ↓
my-agent 输出答案 → git-cnb / CNB API 以 NPC 身份回写评论

`.cnb/settings.yml` —— 定义 NPC 角色

新版 CNB NPC 配置推荐把角色放在 npc.roles 下：

yaml

# .cnb/settings.yml
npc:
  defaultRole: 小光
  roles:
    - name: 小光
      slogan: code is cheap, show me your prompt
      prompt: |
        你叫"小光"，是仓库里的 Coding Agent NPC。
        你擅长阅读代码、定位 bug、写补丁、总结文档。
      enableThinking: true

字段	含义
`defaultRole`	默认 NPC 角色
`roles[].name`	NPC 角色名，@ 时会匹配它
`roles[].slogan`	展示用短句
`roles[].prompt`	角色提示词：能力、口吻、边界
`enableThinking`	是否展示平台支持的思考过程

`.cnb.yml` —— 定义 NPC 事件流水线

教学版采用手写 entrypoint：镜像启动后自动执行 /usr/local/bin/npc-entrypoint。

yaml

# .cnb.yml
.npc: &npc
  - stages:
      - name: run my-agent and reply
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
        env:
          HUNYUAN_API_KEY: ${{ secrets.HUNYUAN_API_KEY }}
          HUNYUAN_BASE_URL: ${{ secrets.HUNYUAN_BASE_URL }}

# 角色名要和 .cnb/settings.yml 里的 roles[].name 对上
小光:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

# 兜底配置：没有按角色名匹配时走这里
$:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

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

关键点

配置	含义
`.npc: &npc`	YAML 锚点，避免 issue / PR 两段重复写
`issue.comment@npc`	有人在 Issue 评论里 @ NPC 时触发
`pull_request.comment@npc`	有人在 PR 评论里 @ NPC 时触发
角色名 key	如 `小光:`，让不同 NPC 角色可以走不同流水线
`$:`	兜底事件配置
`image:`	你构建并推送好的 NPC 镜像
`env:`	从仓库 Secrets 注入 API Key，不要写死在镜像里
`main.push`	默认分支 push 时构建并推送镜像

还有官方插件版

CNB 2026 文档提供了 type: npc:go 内置插件，可以使用平台默认 NPC 执行流程。本课程继续使用 npc-entrypoint，是为了让你亲手看懂取任务、跑 Agent、回写评论三个步骤。

`npc-entrypoint.sh` —— 容器里的粘合脚本

做 3 件事：

从 CNB_NPC_TRIGGER_CONTENT 提取任务文本（去掉 @ mention）
调 my-agent --solo exec "$task" -w "$CNB_WORKSPACE" -o /tmp/answer.md 执行
用 git-cnb 把答案以 NPC 身份回写评论

关键变量：

变量	用途
`CNB_NPC_TRIGGER_CONTENT`	评论原文，里面包含 @ 和用户任务
`CNB_WORKSPACE`	已经 checkout 好的仓库目录
`CNB_ISSUE_IID`	Issue 评论编号
`CNB_PULL_REQUEST_IID`	PR 评论编号
`CNB_REPO_SLUG`	当前仓库路径
`CNB_TOKEN`	平台临时 token，权限受事件和 Work Mode 限制

Work Mode 与权限

NPC 事件默认是自动化行为。CNB 还支持 Work Mode（替我上班），允许 NPC 在满足权限时进行更高权限操作，例如推代码、建分支、创建 MR。

教学版先做回复评论，不要一上来就让 NPC 自动 push。上线时建议遵守三条：

先只读 / 只评论，再逐步开放写权限
所有 Secrets 放平台 Secrets，不写进 prompt / skill / Dockerfile
对写仓库的 NPC 保留日志、分支和 MR 记录，方便回滚

动手试试

把提供的 .cnb.yml 和 .cnb/settings.yml 模板复制到你的仓库根
改 NPC 名字为你想要的（比如 coding-buddy）
在仓库 Settings → Secrets 里加：HUNYUAN_API_KEY + HUNYUAN_BASE_URL
push 一次，让 main.push 构建并推送镜像
在 Issue 里评论：@你的用户名/仓库名(coding-buddy) 介绍下这个项目
等 NPC 回复；失败时先看流水线日志

常见问题排查

症状	原因	解法
NPC 没反应	角色名、@ 格式或事件配置不匹配	检查 `.cnb/settings.yml` 的 `roles[].name` 和评论里的名字
流水线报"镜像不存在"	还没 push 构建镜像 / 镜像地址写错	先触发 `main.push`，确认 registry 里有镜像
`GLIBC_x.y not found`	builder 和 runtime 系统版本不对齐	Dockerfile 两阶段用同一 Debian 版本
NPC 回复为空	`my-agent` 执行失败或输出文件没写入	看流水线 stderr 和 `/tmp/answer.md`
API Key 不存在	Secrets 没配或 env 名写错	检查仓库 Secrets 与 `.cnb.yml` 的 `env`
能回复但不能改仓库	没有 Work Mode 或 token 权限不足	确认是否需要写权限，不要默认放开
本地 docker run 直接失败	ENTRYPOINT 是 `npc-entrypoint`，缺少 CNB 环境变量	本地调试用 `--entrypoint my-agent` 或 `--entrypoint bash`

小结

.cnb/settings.yml 定义 NPC 角色（defaultRole + roles）
.cnb.yml 定义 NPC 事件流水线（什么事件 → 跑什么镜像）
npc-entrypoint.sh 是教学版粘合脚本（读事件 → 调 Agent → 回写评论）
Secrets、Work Mode、日志和镜像 smoke test 是上线时最容易漏的四件事

第 36 节 · CNB Pipeline + NPC 配置 ​

一句话回答 ​

完整链路回顾 ​

.cnb/settings.yml —— 定义 NPC 角色 ​

.cnb.yml —— 定义 NPC 事件流水线 ​

关键点 ​

npc-entrypoint.sh —— 容器里的粘合脚本 ​

Work Mode 与权限 ​

动手试试 ​

常见问题排查 ​

小结 ​