NPC：让 AI 替你干活

在 Issue 或 PR 评论里 @CodeBuddy 并说需求，平台为它启动一条流水线，它执行完把结果回复到评论里。

这就是 NPC。CNB 里它不是游戏角色，而是自动化角色。

一、委托代理模型

官方文档里这套说法最准确，值得完整理解：

• 当事人（principal）：发起委托的人，即 @ 它的那个用户。平台按当事人的角色给 NPC 签发临时令牌
• 代理人（agent）：NPC 本身，以当事人名义在范围内代办，对外显示为 NPC 身份
• 代理权（delegated authority）：当事人授予的权限范围，受三重约束

三重约束是重点：

约束	内容
限时	仅本次任务有效，任务结束或流水线销毁自动终止
限地	仅限当前仓库（可由根组织管理员放开到整个根组织）
限权	角色上限为开发者（Developer），人到不了更高

一句话：NPC 永远不可能比点它的那个人权限更大。

二、两类 NPC

• 系统 NPC：平台内置，现在就是 CodeBuddy，直接 @CodeBuddy
• 自定义 NPC：你在仓库里定义的角色，用 @仓库路径(角色名) 提及

@CodeBuddy 帮我实现这个 Issue
@my-group/my-repo(专家) 帮我回答下这个问题

三、工作模式：能不能写代码的分水岭

默认情况下 NPC 只能读代码、写评论。要让它写代码、推分支、发 PR，必须开 「替我上班」。

开启后可以：

• 编写代码、推送代码、创建分支
• 创建合并请求
• 按评审意见修改代码
• 闭环解决 Issue

代价是权限更高，所以要求操作人至少有开发者权限。

令牌权限的差异（记结论就行）：

场景	代码	PR	Issue/评论	制品库
工作模式	读写	读写	读写	读写
非工作模式 / 不可信事件	只读	只读	读写	只读
可信事件	读写	读写	读写	读写

四、NPC 事件与几条限制

两种事件：

• issue.comment@npc：Issue 描述或评论中提及
• pull_request.comment@npc：PR 描述、评审、评审评论、评论中提及

限制：

• 重新打开 Issue/PR，或编辑描述/评论，不会重新触发
• 一次最多触发 10 个 NPC 事件
• 评论数超过 100 条后不再触发
• 以下位置的 @ 不生效：引用块、代码块、折叠块、有序/无序列表、表格、部分 HTML 标签

代码版本方面：

• issue.comment@npc → 默认分支最新 commit
• pull_request.comment@npc → PR 目标分支最新 commit（跨仓 Fork PR 且触发者是 PR 提交者时，克隆源仓库源分支）
• PR 已合并 → 克隆合并后 commit，可配合 git cherry-pick 同步到其他分支

五、让 NPC 看图

在评论里直接粘贴截图（错误信息、界面、流程图），要求它分析即可，支持 PNG / JPEG / WebP / GIF。

超过 512 KiB 的图会被容器内 ffmpeg 自动压缩后再送给模型（原文件不动）。

能不能真读图取决于两件事：平台 NPC_CONFIG 里声明了 supportImage: true，且底层模型支持图片输入。两者都满足才行。

自定义模型时要注意：supportImage 不继承平台默认配置，会回落成 false。要用就显式写上。

六、安全边界（该警惕的地方）

• 优先选可信仓库的 NPC：NPC 的流水线配置来自 NPC 所属仓库，那个仓库被别人改，你就跟着跑别人的配置
• 敏感动作隔离：涉及密钥、部署、生产数据的任务，放在 push / tag_push 这类可信事件里，别放在评论触发的 NPC 事件里
• 密钥引用会让 NPC 不可分享：一旦 NPC 的流水线通过 imports 等引用了密钥仓库文件，这个 NPC 就不会出现在 NPC 榜单里

七、什么时候 NPC 特别好用

• 刚接手一个仓库，让人读代码解释架构
• 一堆 Issue 要批量补信息、改标签
• PR 例行审查，先让 AI 过一遍再人工看
• 写 .cnb.yml——它比翻文档快

什么时候不适合：涉及生产密钥的操作、需要业务判断的决策、改动面超大的重构。