---
url: /zh/repo/settings-npc.md
description: |
  介绍如何通过 .cnb/settings.yml 为仓库配置专属 AI 助手（NPC）， 包括角色定义、知识库引入、提示词设置和知识库按钮定制。
---
为仓库配置专属 AI 助手的角色、知识库和交互按钮，注入智能协作能力。

## 使用场景

* 配置专属 AI 角色，辅助代码审查和问题解答
* 引入其他仓库的 AI 配置，实现知识共享
* 定制知识库按钮，提升 AI 助手可发现性
* 通过提示词定义角色专业领域和沟通风格

## 最小配置

只需配置一个角色，即可为仓库提供一个可被 `@` 提及的 AI 助手：

```yaml title=".cnb/settings.yml"
npc:
  roles:
    - name: 专家
      prompt: |
        你以"专家"自称，致力于提供专业、准确的技术解答。
```

配置后即可在 Issue 或 PR 评论中通过 `@仓库路径(专家)` 使用。
更多使用与自定义说明，参考 [NPC](../build/npc.md#快速上手)。

## 配置方式

在 `.cnb/settings.yml` 中添加 `npc` 配置：

```yaml title=".cnb/settings.yml"
npc:
  imports:
    list:
      - cnb/docs
  roles:
    - name: 代码助手
      slogan: code is cheap, show me your prompt
      prompt: 你现在是代码助手，专注于协助编写和优化代码
      enableThinking: false
      avatar:
        src: ".cnb/knowledge-base-hover.png"
    - name: 审查员
      prompt: |
        你是一名代码审查员，专注于代码质量把控和改进建议。
  defaultRepo: "cnb/docs"
  defaultRole: "审查员"
  button:
    name: "快速问AI"
    description: "点火，启动 AI!"
    hoverImage: ".cnb/knowledge-base-hover.png"
```

## 参数说明

### 引入配置

| 参数                 | 类型       | 默认值 | 说明                      |
| ------------------ | -------- | --- | ----------------------- |
| `npc.imports.list` | string\[] | -   | 要引入的仓库路径列表，如 `cnb/docs` |

### 角色配置

| 参数                           | 类型      | 默认值  | 说明                   |
| ---------------------------- | ------- | ---- | -------------------- |
| `npc.roles[].name`           | string  | -    | 角色名称                 |
| `npc.roles[].slogan`         | string  | -    | 角色标语                 |
| `npc.roles[].prompt`         | string  | -    | 角色描述提示词              |
| `npc.roles[].enableThinking` | boolean | true | 是否开启思考模式             |
| `npc.roles[].avatar.src`     | string  | -    | 头像图片路径，仅支持仓库默认分支中的图片 |

### 全局配置

| 参数                | 类型     | 默认值 | 说明           |
| ----------------- | ------ | --- | ------------ |
| `npc.defaultRepo` | string | -   | 知识库弹窗默认选中的仓库 |
| `npc.defaultRole` | string | -   | 知识库弹窗默认选中的角色 |

### 知识库按钮配置

| 参数                       | 类型     | 默认值 | 说明                 |
| ------------------------ | ------ | --- | ------------------ |
| `npc.button.name`        | string | -   | 按钮名称               |
| `npc.button.description` | string | -   | 按钮描述               |
| `npc.button.hoverImage`  | string | -   | 悬浮图片，仅支持仓库默认分支中的图片 |

:::tip
角色头像和知识库按钮的悬浮图片仅支持使用仓库默认分支中的文件，填写相对仓库根目录的路径即可。
:::