---
url: /zh/build/internal-steps/knowledge/update.md
description: |
  将 Issue、仓库文档等构建入知识库， 用于搭建可供检索或 RAG（检索增强生成）调用的知识库，随代码提交或 Issue 变更自动同步。
---
`knowledge:update`

**更新知识库**，用于将 Issue、仓库文档等构建入知识库。

**使用场景**：希望用仓库内容搭建知识库、供检索或 `RAG`（检索增强生成）应用调用时使用——
例如把仓库文档与 Issue 切片、向量化后写入知识库，随代码提交或 Issue 变更自动同步。
切片、向量化、增量同步等步骤写脚本成本较高，`knowledge:update` 把这一步收敛成一个内置任务。

* [适用事件](#knowledge-update-applicable-events)
* [工作机制](#knowledge-update-how-it-works)
* [增量更新](#knowledge-update-incremental)
* [参数](#knowledge-update-parameters)
* [配置样例](#knowledge-update-configuration-examples)

## 适用事件 {#knowledge-update-applicable-events}

[所有事件](../../trigger-rule.md#trigger-event)

不同事件走不同的执行路径，详见[工作机制](#knowledge-update-how-it-works)。

## 工作机制 {#knowledge-update-how-it-works}

任务触发后，会先根据触发事件类型选择执行路径：

| 触发事件 | 执行路径 | 说明 |
| --- | --- | --- |
| `issue.*`（Issue 相关事件） | 就地更新 | 不依赖 Runner 与插件镜像，直接调用平台接口增量同步 Issue |
| 其他事件（如 `push`、`tag_push`） | 插件构建 | 拉起 `cnbcool/knowledge-base` 插件镜像，按 Git 提交差异构建仓库文档 |

两条路径的公共流程为：

拉取内容 -> 切片 -> 向量化 -> 进入知识库

其中 Issue 会按以下结构转换为 Markdown 后入库：基本信息（状态、创建者、处理人、
优先级、标签、创建/更新时间）、描述、全部评论（含评论人与时间）。

### 校验与重建 {#knowledge-update-how-it-works-rebuild}

每次执行时会与知识库现有配置比对，若以下任一条件变化，则视为**需要重建**：
删除现有知识库后重新创建，并执行一次全量构建。

* `include`、`exclude` 变化
* `embeddingModel` 变化
* `chunkSize`、`chunkOverlap` 变化
* `issueSyncEnabled` 变化
* `issueState`、`issueLabels`、`issueExcludeLabels` 变化
* 知识库尚无任何构建记录（提交或 Issue 同步记录均为空）
* `forceRebuild` 为 `true`

::: tip 提示
重建会清空已有知识库内容并重新全量构建，耗时更长。
仅调整 `issue*` 之外的参数时才需要重建，日常 Issue 变更走增量更新。
:::

## 增量更新 {#knowledge-update-incremental}

当触发事件为 `issue.*`（如创建 Issue、追加评论）时，任务会**增量更新**知识库，
而不是全量重建：

* 依据知识库记录的**上次同步时间**，只拉取该时间之后有更新的 Issue
* 每个待处理 Issue 在写入前会先删除其旧文档，再写入最新内容，保证「标题/描述/评论」
  的增删改都能同步到知识库
* 处理完成后，推进「上次同步时间」，下次只需同步新的变更

首次执行、或发生[重建](#knowledge-update-how-it-works-rebuild)时，会退化为**全量同步**。

### 过滤条件变化时的清理 {#knowledge-update-incremental-filter-cleanup}

增量模式下，若配置了 `issueState`、`issueLabels` 或 `issueExcludeLabels`，
任务会额外做一次「过滤条件比对」：把**已不再匹配过滤条件**的 Issue 文档从
知识库中删除，避免它们残留在知识库中。

### 同步时间推进与失败处理 {#knowledge-update-incremental-sync-time}

「上次同步时间」只有在以下情况才会被推进：

* 全部 Issue 处理成功
* 存在失败但设置了 `ignoreProcessFailures: true`（此时失败清单会打印在流水线日志中）

若存在失败且未忽略失败，任务会报错退出，且不推进同步时间，下次执行会重新同步这批 Issue。
无权限的 Issue 会被跳过（记录在日志中），不影响同步时间推进。

## 参数 {#knowledge-update-parameters}

以下列表按「文档 / Issue」用途分组概览全部参数。

* [include](#knowledge-update-parameters-include)：需要纳入知识库的文件，`Glob` 匹配
* [exclude](#knowledge-update-parameters-exclude)：需要排除的文件，`Glob` 匹配
* [chunkSize](#knowledge-update-parameters-chunkSize)：文本分块大小
* [chunkOverlap](#knowledge-update-parameters-chunkOverlap)：相邻分块的重叠 token 数
* [embeddingModel](#knowledge-update-parameters-embeddingModel)：嵌入模型（仅支持 `hunyuan`）
* [issueSyncEnabled](#knowledge-update-parameters-issueSyncEnabled)：是否同步 Issue 进知识库
* [issueState](#knowledge-update-parameters-issueState)：仅同步指定状态的 Issue（`open`/`closed`）
* [issueLabels](#knowledge-update-parameters-issueLabels)：仅同步指定标签的 Issue
* [issueExcludeLabels](#knowledge-update-parameters-issueExcludeLabels)：排除指定标签的 Issue（优先级更高）
* [forceRebuild](#knowledge-update-parameters-forceRebuild)：是否删除知识库并重新构建
* [ignoreProcessFailures](#knowledge-update-parameters-ignoreProcessFailures)：有文件处理失败时是否仍更新知识库

各参数详细说明如下。

### include {#knowledge-update-parameters-include}

* type: `String` | `Array<String>`
* required: `false`
* default: `**/**.md`

指定需要包含的文件，使用 `Glob` 模式匹配，默认为 `**/**.md`（包含所有 Markdown 文件），
支持数组或逗号分隔。当前支持的文件类型有：.md、.mdx、.docx、.txt、.pdf。

### exclude {#knowledge-update-parameters-exclude}

* type: `String` | `Array<String>`
* required: `false`

指定需要排除的文件，使用 `Glob` 模式匹配，默认不排除任何文件，支持数组或逗号分隔。

### chunkSize {#knowledge-update-parameters-chunkSize}

* type: `Number`
* required: `false`
* default: `1500`

指定文本分块大小。

### chunkOverlap {#knowledge-update-parameters-chunkOverlap}

* type: `Number`
* required: `false`
* default: `0`

指定相邻两个分块之间的重叠 token 数量。

### embeddingModel {#knowledge-update-parameters-embeddingModel}

* type: `String`
* required: `false`
* default: `hunyuan`

嵌入模型，目前仅支持 `hunyuan`。

### issueSyncEnabled {#knowledge-update-parameters-issueSyncEnabled}

* type: `Boolean`
* required: `false`
* default: `true`

是否启用 Issue 同步功能。启用后会自动拉取仓库的 Issue 数据并加入知识库。

### issueState {#knowledge-update-parameters-issueState}

* type: `String`
* required: `false`

仅同步指定状态的 Issue，默认包含全部 Issue，可选值为 `open` | `closed`。

### issueLabels {#knowledge-update-parameters-issueLabels}

* type: `String` | `Array<String>`
* required: `false`

仅同步指定标签的 Issue，默认包含全部 Issue，支持数组或逗号分隔。

### issueExcludeLabels {#knowledge-update-parameters-issueExcludeLabels}

* type: `String` | `Array<String>`
* required: `false`

排除带有指定标签的 Issue，默认不排除任何 Issue，支持数组或逗号分隔。
当与 `issueLabels` 存在交集时，exclude 优先。

### forceRebuild {#knowledge-update-parameters-forceRebuild}

* type: `Boolean`
* required: `false`
* default: `false`

是否删除知识库并重新构建。当设置为 `true` 时，删除并重新创建知识库。

### ignoreProcessFailures {#knowledge-update-parameters-ignoreProcessFailures}

* type: `Boolean`
* required: `false`
* default: `false`

是否忽略文档处理失败。当设置为 `true` 时，即使有文件处理失败也会更新知识库。

## 配置样例 {#knowledge-update-configuration-examples}

### push 到 main 分支时重建知识库 {#knowledge-update-configuration-examples-basic-usage}

按 Git 提交差异构建仓库文档。

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: build knowledge base
          type: knowledge:update
          options:
            include: "**/**.md"
```

### Issue 创建时增量追加进知识库 {#knowledge-update-configuration-examples-issue-open}

Issue 事件流水线需挂靠在 `$` 下，仓库有新的 Issue 创建时立即触发一次知识库更新。

```yaml title=".cnb.yml"
$:
  issue.open:
    - stages:
        - name: build knowledge base
          type: knowledge:update
          options:
            # 仅同步 open 状态的 Issue
            issueState: open
```

### Issue 更新时增量同步进知识库 {#knowledge-update-configuration-examples-issue-update}

当 Issue 的名称、描述、处理人、标签、优先级变更时触发。

```yaml title=".cnb.yml"
$:
  issue.update:
    - stages:
        - name: build knowledge base
          type: knowledge:update
          options:
            # 仅同步带「文档」标签的 Issue，并排除带「无需入库」标签的 Issue
            issueLabels:
              - 文档
            issueExcludeLabels:
              - 无需入库
```

### Issue 关闭时仅重建文档知识库 {#knowledge-update-configuration-examples-issue-close}

若不希望已关闭的 Issue 继续留在知识库中，可在关闭时只重建仓库文档部分。

```yaml title=".cnb.yml"
$:
  issue.close:
    - stages:
        - name: build knowledge base
          type: knowledge:update
          options:
            # 关闭 Issue 同步，仅构建仓库文档
            issueSyncEnabled: false
```