CNB 文档

简体中文

English

简体中文

English

外观

knowledge:update

复制页面

1861 字约 6 分钟

knowledge:update

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

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

适用事件

所有事件

不同事件走不同的执行路径，详见工作机制。

工作机制

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

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

两条路径的公共流程为：

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

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

校验与重建

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

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

提示

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

增量更新

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

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

首次执行、或发生重建时，会退化为全量同步。

过滤条件变化时的清理

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

同步时间推进与失败处理

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

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

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

参数

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

各参数详细说明如下。

include

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

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

exclude

  • type: String | Array<String>
  • required: false

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

chunkSize

  • type: Number
  • required: false
  • default: 1500

指定文本分块大小。

chunkOverlap

  • type: Number
  • required: false
  • default: 0

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

embeddingModel

  • type: String
  • required: false
  • default: hunyuan

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

issueSyncEnabled

  • type: Boolean
  • required: false
  • default: true

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

issueState

  • type: String
  • required: false

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

issueLabels

  • type: String | Array<String>
  • required: false

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

issueExcludeLabels

  • type: String | Array<String>
  • required: false

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

forceRebuild

  • type: Boolean
  • required: false
  • default: false

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

ignoreProcessFailures

  • type: Boolean
  • required: false
  • default: false

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

配置样例

push 到 main 分支时重建知识库

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

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

Issue 创建时增量追加进知识库

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

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

Issue 更新时增量同步进知识库

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

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

Issue 关闭时仅重建文档知识库

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

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