logo
c.d/npc-playground
Public
0
0
WeChat Login
CodeIssuesPull requestsEventsPackagesInsights
main
npc-playground/README.md
竹蜻蜓
docs: Continuously writing code using NPC
900a8e4e
0 commits

🎮 NPC Playground

我替你上班，你替我自由 —— 让 NPC 帮你处理繁琐工作，把时间留给真正重要的事

🤖 什么是 NPC？

NPC 是 CNB 开源平台推出的 AI 角色功能，基于 Docker 构建，与代码仓库同源共生 —— 代码在哪里，Agent 就在哪里。你不想做的事情，NPC 帮你做。

你不想做的事NPC 帮你做
😫 重复回答相似问题🤖 自动回复 Issue 评论
😫 审查枯燥的代码🤖 自动 PR 代码审查
😫 查找文档翻半天🤖 基于知识库即时问答
😫 手动创建重复 Issue🤖 批量创建、分类管理
😫 记不住项目细节🤖 记住一切，随问随答
😫 不想写的代码🤖 NPC 帮你写

从技术角度看，NPC 是一个以 Issue / PR 事件驱动、以云原生为底座、以 Docker 为运行环境的 [AI] Agent。

📦 如何使用 NPC

CNB 提供了多种不同类型的 NPC：

类型说明运行镜像配置成本
系统 NPC（CodeBuddy）平台内置，全局可用default-codebuddy-npc零配置
当前仓库默认NPC在仓库中自定义的 NPCdefault-npc-agent需配置 .cnb/settings.yml
当前仓库自定义NPC在仓库中自定义的 NPCcnb.yml 中配置的镜像需配置 .cnb/settings.yml + .cnb.yml
别人的NPC在当前仓库使用其他仓库的 NPC由其他仓库的 NPC 定义star 仓库即可

工作流程

无论哪种 NPC，工作流程都一样：

"替我上班"模式

替我上班

在 ISSUE、PR 评论中开启 替我上班 后，NPC 流水线将获得更高的操作权限。未开启时，NPC 仅能以只读方式响应。

未开启已开启
Token 权限只读读写（可推送代码、创建 PR）
适用场景问答、知识查询写代码、自动提 PR、合并分支

📖 权限详情参见：CNB Token 权限说明

社区 优秀NPC 示例

NPC仓库功能
OpenClawBring/AGI/OpenClawOpenClaw 是一个用于构建、运行和编排 AI Agent 的通用框架，支持对话、工具调用与多模型接入
OpenCodenpc/open-code基于 OpenCode CLI 的 CNB 平台 AI Bot
以鹅传鹅-Pronpc/mtga在任意 CNB 仓库的 Issue 或合并请求（PR）评论中 @NPC 即可触发，AI 会自动分析上下文并完成任务。
πnpc/pai随机召唤其他 NPC 回答问题
都闭嘴Anyexyz/Tools/kill-cnb-npc一键让其他 NPC 闭嘴

举个🌰。在 PR 评论或 ISSUE 中发送：

@npc/pai(π) 你帮我看看
@npc/open-code(OpenCode) 帮我根据当前的 issue 修改一下代码，修改完后提交个 pr 上来
@Bring/AGI/OpenClaw(OpenClaw) 帮我查看上海明天的天气
@Anyexyz/Tools/kill-cnb-npc(都闭嘴) 让他们都闭嘴

💡 浏览更多社区 NPC：https://cnb.cool/explore

🛠️ 自定义 NPC

想要一个完全符合你需求的 NPC？两步搞定🤝。

Step 1：定义 NPC 人设

在仓库创建 .cnb/settings.yml，设定 NPC 的身份和行为：

# .cnb/settings.yml
npc:
  roles:
    - name: 小助手
      avatar:
        src: https://cnb.cool/${your-repo}/-/git/raw/main/avatar.png
      prompt: |
        你是一个友好、专业的代码助手。
        擅长回答代码、Git、CI/CD 相关问题。
        回答简洁准确，必要时提供代码示例。

这里的 https://cnb.cool/${your-repo}/-/git/raw/main/avatar.png 是一个示例，在定义 NPC 的时候，需要填入正确的地址。例如：https://cnb.cool/cnb/feedback/-/git/raw/main/assets/feedmiao.jpg。图片地址也支持自己仓库中已存在的图片，例如 .cnb/asset/lulu.jpg（仓库内的全局路径）。

Step 2：配置触发场景（可选）

创建 .cnb.yml，告诉 NPC 什么时候工作。本质上是运行一条 CNB 流水线，所以这里兼容 CNB 流水线的所有语法。

如果不配置触发场景，默认使用 default-npc-agent 镜像。

# .cnb.yml
.npc_task: &npc_task
  - stages:
      - name: npc respond
        image: docker.cnb.cool/npc/mtga:latest # 也可以替换成任意一个 NPC 镜像

小助手:
  issue.comment@npc: *npc_task        # 有人在 Issue 评论中 @小助手
  pull_request.comment@npc: *npc_task  # 有人在 PR 评论中 @小助手

附：NPC 相关的环境变量

NPC 流水线运行时，以下 NPC 相关环境变量会自动注入， 完整的环境变量请参考 CNB 环境变量。

NPC 自身信息

环境变量说明
CNB_NPC_SLUGNPC 所属仓库路径（原始格式）
CNB_NPC_SLUG_LOWERCASENPC 所属仓库路径（小写格式）
CNB_NPC_NAMENPC 角色名
CNB_NPC_SHANPC 仓库默认分支最新 SHA
CNB_NPC_PROMPTNPC 角色 Prompt
CNB_NPC_AVATARNPC 角色头像
CNB_NPC_ENABLE_THINKINGNPC 是否开启思考
CNB_NPC_ENABLE_WORKMODENPC 是否开启工作模式

触发者信息

环境变量说明
CNB_BUILD_USER_NPC_SLUG触发构建的NPC 的 Slug
CNB_BUILD_USER_NPC_NAME触发构建的NPC 的名称
CNB_BUILD_USER触发构建的用户名
CNB_BUILD_USER_NICKNAME构建触发的用户昵称
CNB_COMMENT_BODY触发构建的评论内容

🎬 实战场景

场景 1：极简 Hello World

最简单的 NPC：用户 @NPC，固定回复 hello, world。无需 AI，无需复杂逻辑。

涉及的文件如下：

hello-world/
├── Dockerfile
└── entrypoint.sh
.cnb.yml
.cnb
  └── settings.yml

💡 NPC 核心工作原理：用户触发 → 流水线运行 → 结果回复到评论区

场景 2：使用 NPC 来做代码 Review

方式一：PR 自动触发（全自动，无需 @NPC）

利用 CNB 流水线的 pull_request 事件驱动，只要有 PR 创建或更新，就会自动运行 AI 代码审查 + 自动分配人工评审人，无需手动干预。

涉及的配置（.cnb.yml）：

# 1. 定义 review 任务
.reviewer: &reviewer
  stages:
  # AI 自动代码审查（使用 cnbcool/code-review 插件）
  # 文档：https://docs.cnb.cool/zh/plugin/#public/cnbcool/code-review
  - name: AI code review
    image: cnbcool/code-review:latest
    settings:
      output: ./code_review.json    # 审查结果保存为 JSON
      context: 10                   # 每处变更展示上下文 10 行
      comment: true                 # 审查结果以评论形式发到 PR
      max_comments: 2               # 最多 2 条评论，避免刷屏
      fail_on_critical: false       # 有严重问题也不阻断流水线
      prompt_output: ./prompt.txt   # 导出发给 AI 的 prompt（方便调试）
  # 自动分配人工评审人
  # 文档：https://docs.cnb.cool/zh/build/internal-steps.html#git-reviewer
  - name: Add reviewer
    type: git:reviewer
    options:
      type: add-reviewer
      reviewers:                    # 候选评审人池
      - Alice
      - Bob
      - Charlie
      - David
      count: 3                      # 从候选人中随机选 3 人

# 2. 绑定到所有分支的 PR 事件（$ 是兜底通配符，匹配所有未明确指定的分支）
$:
  pull_request:
    review: *reviewer

流程：

无需 @任何人，提交 PR 的那一刻，审查就开始了。

方式二：在 PR 评论中 @NPC 主动触发 Review

除了全自动触发，你也可以直接在 PR 评论中 @NPC 来主动触发代码审查。不需要使用特殊的 Review 插件镜像，任何自定义 NPC 甚至默认 NPC 都能做 Review——NPC 天然能读取 PR 的上下文和变更内容。适用于以下场景：

  • 只想对特定 PR 进行审查，而不是所有 PR 都自动审查
  • PR 更新后想要重新触发一次审查
  • 想让不同的 NPC 角色以不同风格审查代码

配置方式：

只需在 .cnb/settings.yml 中定义一个角色，通过 prompt 赋予它代码审查的人设即可：

# .cnb/settings.yml
npc:
  roles:
    - name: 代码审查官
      avatar:
        src: https://cnb.cool/${your-repo}/-/git/raw/main/reviewer-avatar.png
      prompt: |
        你是一位严格的代码审查专家。
        关注代码质量、安全漏洞、性能问题和最佳实践。
        请对当前 PR 的变更内容逐文件给出审查意见。

💡 如果不在 .cnb.yml 中配置自定义流水线，该角色会自动使用 default-npc-agent 默认镜像运行，已经足够完成代码审查。

使用方式：

在 PR 的评论区中输入：

@代码审查官 帮我 review 一下这个 PR

NPC 就会启动流水线，对当前 PR 的变更文件进行审查，并将结果回复到评论区。

两种方式对比

方式一：PR 自动触发方式二：@NPC 主动触发
触发方式创建/更新 PR 时自动运行在 PR 评论中 @NPC
配置位置.cnb.yml 中 .$.pull_request.cnb/settings.yml（仅需定义角色）
适用场景所有 PR 统一审查按需审查、重复审查
是否需要先创建 NPC 角色不需要需要定义角色
可定制性全局统一策略可为不同角色配置不同策略

💡 两种方式可以同时使用：自动触发保证每个 PR 都有基础审查，@NPC 用于需要额外关注的 PR。

场景 3：使用 NPC 持续写代码

NPC 不只能写一次代码——它可以根据 Review 意见持续迭代，形成 "提需求 → 写代码 → 审查 → 修改" 的自动化循环。

你只需要提一个 Issue，然后喝杯咖啡☕️，回来看看 PR 是否满意即可。

参考 Issue：空文件被误判为二进制文件。

NPC 增强

添加 Skills

这里以默认 NPC 镜像 (基于 Codebuddy 实现) 为例，我们可以使用 Skills 来增加默认默认 NPC 的能, Codebuddy 的 Skills 分为用户级和项目级，路径分别为 ~/.codebuddy/skills 和 /workspace/.codebuddy/skills, 可以通过在代码仓库中增加 skills 来增加 npc。

直接在仓库中创建 .codebuddy/skills/ 目录，NPC 运行时会自动加载：

your-repo/
└── .codebuddy/
    └── skills/
        └── my-skill
              └── SKILL.md

2. 添加环境依赖

默认 NPC 运行在基础 NodeJS 镜像中。如果你的项目需要特定的语言运行时、skills、工具链或依赖，可以自定义 NPC 的运行环境。

推荐使用 npc:go 内置步骤，自行构建镜像即可。 参考文档：https://docs.cnb.cool/zh/build/internal-steps.html#npc

自定义 Docker 镜像

以 Go 开发环境为例：

# npc-go/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

# 安装 Go
ARG GO_VERSION=1.24.5
RUN wget -q https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz -O /tmp/go.tar.gz &&\
    tar -C /usr/local -xzf /tmp/go.tar.gz && rm /tmp/go.tar.gz

ENV PATH=/usr/local/go/bin:/root/go/bin:${PATH}
RUN go install -v golang.org/x/tools/gopls@latest

在 .cnb.yml 中使用 npc:go

.npc_go: &npc_go
  - docker:
      image: ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}/npc-go:latest
    stages:
      - name: npc go
        type: npc:go

码农go:
  issue.comment@npc: *npc_go
  pull_request.comment@npc: *npc_go

💬 使用感受

  • 泡咖啡前 @NPC 提个需求，咖啡端回来代码已经写好了 —— 手机上就能指挥干活，对移动办公极其友好。

  • 每一次对话、每一行代码、每一步思考过程都沉淀在 Issue 和 PR 中，全程可追溯，不怕丢上下文。

© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
SKILL
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号