CNB 自定义 NPC 创建工作流

> v1.0 · 2026-04-24 · 基于「灵鉴」PR审查NPC实战复盘
> 参考架构：CNB 官方 NPC 工程师方案二（issue #959）

一、工作流总览

需求确认 → Fork参考NPC → 改造配置 → 创建密钥仓库 → 推送代码 → 转移到目标组织 → 关联密钥仓库 → 测试验证 → 上线

二、前置条件

三、详细步骤

Step 1: 需求确认

确认清单：
1. NPC 功能定位？（代码审查/技术客服/文档助手/通用）
2. 接入什么大模型？（GLM-5.1 / GPT-4 / DeepSeek 等）
3. NPC 名字和口号？
4. 部署到哪个组织？
5. 是否需要专属头像？

提示词模板：

确认 NPC 创建需求：
- 功能定位：[代码审查/技术客服/文档助手/通用]
- 大模型：[GLM-5.1/GPT-4/DeepSeek/其他]
- API 端点：[URL]
- NPC 名称：[名称]
- 部署组织：[组织名]
- 参考NPC：[fork来源仓库]

Step 2: Fork 参考 NPC 仓库

⚠️ API 不支持 fork 操作（errcode 9），必须用 git clone。

# 克隆参考 NPC 仓库
git clone https://{username}:{CNB_TOKEN}@cnb.cool/{参考NPC仓库路径}.git /tmp/{npc-name}
cd /tmp/{npc-name}
git checkout -b main  # 确保分支名是 main

创建新的 NPC 仓库（API）：

curl -s -X POST \
  -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Content-Type: application/json" \
  "${CNB_API_ENDPOINT}/{username}/-/repos" \
  -d '{
    "name": "{npc-name}",
    "description": "{NPC描述}",
    "visibility": "private"
  }'

推送到新仓库：

cd /tmp/{npc-name}
git remote remove origin
git remote add origin https://{username}:{CNB_TOKEN}@cnb.cool/{username}/{npc-name}.git
git push -u origin main

Step 3: 改造 NPC 配置

3.1 角色配置 .cnb/settings.yml

npc:
  roles:
    - name: {NPC名称}
      slogan: "{一句话口号}"
      prompt: |
        你是{角色定位}，负责{具体职责}。
        你的任务：
        1. {任务1}
        2. {任务2}
        3. {任务3}
        回复要求：
        - 使用 Markdown 格式回复
        - 语气专业、友好
        - 控制在 {字数} 字以内
      avatar:
        src: ".cnb/avatar.svg"

Prompt 设计原则：
- 明确角色身份和专业领域
- 列出具体任务清单（编号）
- 定义回复格式要求
- 设置字数控制
- 如需引用知识库，加上参考链接

3.2 自定义 Skill .codebuddy/skills/my-llm/SKILL.md

这是核心！NPC Agent 框架会按 Skill 指令调自定义大模型。

---
name: my-llm
description: 调用自有大模型 API 生成回复
allowed-tools: Bash
---

# 调用自有大模型

当需要回复用户时，执行以下步骤：

## 步骤 1：获取相关信息（如 PR diff）
\```bash
curl -s -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  "$CNB_API_ENDPOINT/$CNB_REPO_SLUG/-/pulls/$CNB_EVENT_ISSUE_NUMBER"
\```

## 步骤 2：拼接 Prompt
将获取的信息整合为 system prompt + user prompt。

## 步骤 3：调用大模型 API
\```bash
curl -s ${YOUR_LLM_API_URL}/chat/completions \
  -H "Authorization: Bearer ${YOUR_LLM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.1",
    "messages": [
      {"role": "system", "content": "你是{角色}，{能力描述}"},
      {"role": "user", "content": "{用户问题/PR信息}"}
    ],
    "temperature": 0.3,
    "max_tokens": 4096
  }' | jq -r '.choices[0].message.content'
\```

## 步骤 4：发表评论
\```bash
cnb issues comment --body "回复内容"
\```

Skill 设计要点：
- allowed-tools: Bash — 必须声明，否则无法执行 curl
- 用环境变量引用 API Key（${YOUR_LLM_API_KEY}），不硬编码
- CNB 环境变量自动注入：$CNB_TOKEN、$CNB_REPO_SLUG、$CNB_EVENT_ISSUE_NUMBER
- 根据 NPC 功能调整步骤（PR审查需获取diff，客服需知识库检索等）

3.3 流水线配置 .cnb.yml

# NPC 触发配置（使用 npc:go 模式）
.npc: &npc
  - env:
      YOUR_LLM_API_URL: ((your-llm-api-url))
      YOUR_LLM_API_KEY: ((your-llm-api-key))
      YOUR_MODEL_NAME: ((your-model-name))
    stages:
      - name: npc go
        type: npc:go

# 事件绑定
$:
  pull_request.comment@npc: *npc
  issue.comment@npc: *npc

关键：
- 必须用 npc:go，让平台 NPC Agent 框架调度，它会读取 Skill 指令执行
- 环境变量用 ((变量名)) 引用密钥仓库的文件
- 事件类型按需选择：
- pull_request.comment@npc — PR 评论触发
- issue.comment@npc — Issue 评论触发
- pull_request.open — PR 创建触发
- issue.open — Issue 创建触发

3.4 专属头像 .cnb/avatar.svg

SVG 格式，建议 120×120，辨识度要高。
放到 .cnb/avatar.svg，settings.yml 中引用 src: ".cnb/avatar.svg"。

Step 4: 创建密钥仓库

密钥仓库是独立仓库，文件名=变量名，文件内容=值。

# 创建密钥仓库
curl -s -X POST \
  -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Content-Type: application/json" \
  "${CNB_API_ENDPOINT}/{username}/-/repos" \
  -d '{
    "name": "{npc-name}-secrets",
    "description": "{NPC名称} 密钥仓库",
    "visibility": "private"
  }'

# 创建密钥文件
mkdir -p /tmp/{npc-name}-secrets && cd /tmp/{npc-name}-secrets
git init && git checkout -b main
echo -n "{API_URL}" > your-llm-api-url
echo -n "{API_KEY}" > your-llm-api-key
echo -n "{MODEL_NAME}" > your-model-name
git add -A && git commit -m "init: NPC 密钥配置"
git push -u origin main

Step 5: 提交推送所有变更

cd /tmp/{npc-name}
# 清理不需要的原仓库文件（如企微通知、stale bot 等）
rm -rf {不需要的目录}
git add -A
git commit -m "feat: {NPC名称} - 基于参考NPC改造，接入{模型名}"
git push

Step 6: 转移到目标组织

⚠️ API 不支持转移（errcode 9 管理规则限制），必须网页操作。

提供链接给用户：
- NPC 仓库：https://cnb.cool/{username}/{npc-name}/-/settings → 转移到目标组织
- 密钥仓库：https://cnb.cool/{username}/{npc-name}-secrets/-/settings → 转移到目标组织

转移后路径变为：{目标组织}/{npc-name} 和 {目标组织}/{npc-name}-secrets

Step 7: 关联密钥仓库

⚠️ 只能网页操作，API 无此接口。

在 NPC 仓库设置页面 → 找到密钥仓库配置 → 填入 {目标组织}/{npc-name}-secrets

Step 8: 测试验证

# 在 NPC 仓库创建测试 Issue
curl -s -X POST \
  -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Content-Type: application/json" \
  "${CNB_API_ENDPOINT}/{org}/{npc-name}/-/issues" \
  -d '{
    "title": "测试 NPC 触发",
    "body": "@{org}/{npc-name}({NPC名称}) 测试一下"
  }'

# @ NPC 触发
curl -s -X POST \
  -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  -H "Content-Type: application/json" \
  "${CNB_API_ENDPOINT}/{org}/{npc-name}/-/issues/{number}/comments" \
  -d '{
    "body": "@{org}/{npc-name}({NPC名称}) 请回复一下"
  }'

等待 15-20 秒后检查：

# 查评论
curl -s -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  "${CNB_API_ENDPOINT}/{org}/{npc-name}/-/issues/{number}/comments"

# 查流水线
curl -s -H "Accept: application/vnd.cnb.api+json" \
  -H "Authorization: Bearer $CNB_TOKEN" \
  "${CNB_API_ENDPOINT}/{org}/{npc-name}/-/build/logs"

成功标志： NPC 评论出现（is_npc: true）

Step 9: 在目标仓库引入 NPC

在需要使用该 NPC 的仓库中，编辑 .cnb/settings.yml：

npc:
  imports:
    list:
      - repo: {org}/{npc-name}

推送后，该仓库的 PR/Issue 中就可以 @{org}/{npc-name}({NPC名称}) 触发了。

四、踩坑记录

五、不同场景的 Skill 变体

PR 代码审查 NPC

Skill 步骤：获取 PR diff → 拼接审查 prompt → 调大模型 → 发审查评论

技术客服 NPC

Skill 步骤：知识库检索（如有）→ 拼接回答 prompt → 调大模型 → 发回复

文档助手 NPC

Skill 步骤：获取文档内容 → 分析质量 → 调大模型生成建议 → 发评论

六、实战提示词速查

创建 NPC 一句话

基于 {参考NPC仓库} fork 创建私有 NPC，名称「{名称}」，接入 {模型名}，部署到 {组织}

测试 NPC

在 {org}/{npc-name} 创建 Issue 并 @NPC 测试触发，15秒后查评论和流水线状态

引入 NPC 到目标仓库

在 {目标仓库} 的 .cnb/settings.yml 中添加 npc.imports 引用 {org}/{npc-name}

七、与 cnb-npc-dispatch 的关系

两者互补：先用本 Skill 造 NPC，再用 dispatch Skill 派活。