企业官网建设流程全解析

• AI 应用
• AI 写作
• 人工智能
• AI Agent
• 企业应用

文档知识库是 OpenBidKit_Yibiao（开箱即用的 AI 标书编写工具）中的核心资料沉淀模块：它把历史投标文件、技术方案、管理制度、人员设备清单等资料上传后，自动转换为 Markdown、剔除页眉页脚与目录噪声、按语义提取出可供复用的"知识条目"，并自动匹配段落、补齐遗漏。读完本文，你将掌握从「新建文件夹 → 上传文档 → 等待解析 → 核对条目 → 在目录生成中引用」的完整操作链路，并理解超长文档自动分段解析与补漏的底层机制，能够根据状态提示快速定位和解决解析失败问题。

知识库在项目中的定位

在 Electron 客户端中，知识库是独立的一级功能模块，入口位于左侧导航的知识库 → 文档知识库（对应前端页面 client/src/features/knowledge-base/pages/KnowledgeBasePage.tsx）。它的作用不是简单地把 PDF/Word 存起来，而是把资料加工成可供后续生成任务直接消费的结构化知识：

• 每个文档被拆分为带编号的正文 block（段落块）；
• AI 从中提取「知识条目」（title + resume 摘要），并记录条目与原文段落的对应关系（source_block_ids）；
• 完成后，技术方案的"目录生成"与正文生成可直接引用这些条目作为参考依据。

这一设计在 GenerationSettingsPage.tsx 中也有印证：目录生成模式列表里包含{ id: 'knowledge', label: '知识库' }这一项。

操作顺序总览

按以下五个步骤即可完成知识库的搭建与使用：

1. 点击新建文件夹，按项目或资料类型建立分类；
2. 选中左侧文件夹，再点击上传文档；
3. 等待解析进度达到 100%，文档状态变成"完成"；
4. 点击查看条目或查看 Markdown检查解析结果；
5. 状态为"失败"时，根据提示处理文件后重新解析。

下面逐节展开说明每一步的操作细节与背后的实现逻辑。

第一步：新建文件夹建立分类

进入文档知识库页面后，先点击顶部工具栏的新建文件夹按钮，输入文件夹名称即可创建（对应前端createFolder逻辑，见 KnowledgeBasePage.tsx）。文件夹的典型分类方式有两种：

• 按项目分：某个投标项目相关的全部历史资料放在一个文件夹；
• 按资料类型分：技术方案、项目管理、质量安全、人员设备、类似业绩等各建一个文件夹。

文件夹与文档均支持重命名、删除、拖拽排序与跨文件夹移动（reorderFolder、moveDocument，见 knowledgeBaseService.cjs）。删除文件夹时会连带清理其下的所有文档目录与导入图片缓存；若某个文档正在处理中，会提示"请完成后再删除"。

第二步：上传文档与支持格式

选中左侧文件夹后，点击上传文档会弹出系统文件选择对话框，支持多选。后端在 knowledgeBaseService.cjs 中声明了支持扩展名：

const supportedExtensions = new Set(['.doc', '.docx', '.wps', '.pdf', '.md', '.markdown', '.xls', '.xlsx']);

即Word（doc/docx/wps）、PDF、纯文本 Markdown、Excel（xls/xlsx）都在支持范围内；文件选择对话框的过滤条件与此一致（见 knowledgeBaseService.cjs）。不支持的类型会被自动跳过，全部不支持时返回"未选择支持的文档类型"。

每个上传的文档都会立即被登记为一条pending（等待处理）状态的记录并加入处理队列（prepareDocument，见 knowledgeBaseService.cjs），随后自动开始解析，不需要手动触发。

第三步：等待解析——状态机与进度含义

上传后，文档会经历一条完整的处理流水线，前端通过statusLabels把机器状态映射为中文提示（见 KnowledgeBasePage.tsx）：

处理过程的每个节点都会通过knowledge-base:event事件实时推送到界面（见 knowledgeBaseIpc.cjs），因此你在界面上看到的进度条和状态文案是真实解析进度的实时反映，而不是静态占位。

底层流水线：九个处理步骤

后端把整个解析过程拆成可断点续跑的分步任务（步骤键定义见 knowledgeBaseStore.cjs）：

copy_source → convert_markdown → build_blocks → extract_first_items → extract_supplement_items → merge_candidates → match_batches → recover_missing → save_result

• copy_source：把原始文件复制到知识库目录（folders/<folderId>/documents/<documentId>/）；
• convert_markdown：调用parseDocumentWithConfig将文档转换为 Markdown 并写入content.md（见 knowledgeBaseService.cjs）；
• build_blocks：把 Markdown 切分为语义 block，并过滤噪声（详见下一节）；
• extract_first_items / extract_supplement_items：AI 首轮提取知识条目，再基于全文已有结果补充遗漏条目，最后按标题去重合并（mergeTitleSummaryItems）；
• merge_candidates：为候选条目分配K000001形式的稳定 id（mergeCandidateItems，见 knowledgeBaseService.cjs）；
• match_batches / recover_missing：AI 为每个条目匹配强相关段落，然后多轮补齐遗漏段落；
• save_result：把条目标题、摘要、正文内容与来源 block 回填保存，并生成覆盖率统计报告。

每个步骤都有status记录（idle/running/success/error），已成功的步骤会复用结果；如果中途中断，应用重启后会调用recoverInterruptedDocuments把中断文档标记为"上次任务中断，请点击重试继续处理"（见 knowledgeBaseStore.cjs），你只需点一次重试即可从断点继续，无需重新上传。

超长文档自动分段解析，无需手动拆分

原文档特别强调：超长文档会自动分段解析、匹配前后内容并补齐遗漏，无需手动拆分。这背后是源码中一套完整的上下文预算与分段策略，核心参数如下（见 knowledgeBaseService.cjs）：

const oversizedBlockChars = 8000; // 单个超长 block 的再切分阈值 const semanticMergeTargetChars = 500; // 语义合并的目标字符数 const recoveryMaxAttempts = 2; // 补漏最大轮数 const DEFAULT_CONTEXT_LENGTH_LIMIT = 400000; // 上下文长度默认上限 const KNOWLEDGE_CONTEXT_LIMIT_RATIO = 0.8; // 请求预算占上下文的比率 const TASK_AND_ITEMS_RESERVE_RATIO = 0.2; // 预留给任务说明+条目列表的预算比例 const PROMPT_CACHE_WARMUP_DELAY_MS = 5000; // 提示词缓存预热等待时长

工作机制可以概括为三点：

1. 统一 block 分段（策略 B）：buildUnifiedBlockSegments（knowledgeBaseService.cjs）按requestBudget * (1 - 0.2)预留任务与条目空间后，把全部 block 连续打包成若干段。提取、补充、匹配共用同一张段表，保证三步的 L1 block 前缀提示词字节级一致——这是为了让提示词缓存命中、降低输入成本的关键设计。
2. 预热后并行：多段文档先串行跑第一段以完成提示词缓存写入，等待PROMPT_CACHE_WARMUP_DELAY_MS（5 秒）后再并发处理剩余段落（waitForPromptCacheWarmup+runParallelAndThrowAfterSettled，见 knowledgeBaseService.cjs）。
3. 条目侧兜底拆分：若某段中"任务说明 + 全部条目"超出请求预算，只拆 L2 条目列表、不动 L1 block 前缀（packItemsIntoSegments/getItemSplitBudget），匹配完成后用mergeMatchResults合并同一条目的多子批结果。

同时，build_blocks阶段会通过filterBlocks（knowledgeBaseService.cjs）自动剔除噪声 block，过滤原因包括：

• 空 block、纯页码（第X页/共X页、page N of M）；
• 内容过短（去空白后不足 100 字符）；
• 目录页（含连续点线 + 页码的结构）；
• 重复出现的页眉页脚（同一文本出现 ≥3 次）；
• 封面页（出现"投标文件/项目名称/招标编号"等标记且无长句）；
• 签章页（盖章、签名、法定代表人、授权代表等标记）。

过滤后若没有任何正文 block，会报"筛选后没有可分析的正文内容"。

自动段落匹配与遗漏补漏

条目提取完成后，matchDocument（knowledgeBaseService.cjs）会按统一段表逐段执行匹配：AI 只基于本段出现的 block id 为条目返回闭区间范围（如["P000001","P000003"]），程序再将其还原为具体的block_ids（expandRanges/compressBlockIdsToRanges）。

匹配完成后进入recover_missing补漏环节：找出尚未被任何条目或舍弃组认领的 block，最多进行2 轮（recoveryMaxAttempts）AI 补漏，每个遗漏 block 必须归入三类之一：

• matches：归入已有知识条目；
• new_items：内容有复用价值但无合适条目时，新增知识条目；
• discarded：质量低、重复或格式残留时舍弃，并给出reason。

补漏采用全局优先级认领（matches > new_items > discarded），避免子批顺序导致误判（mergeRecoverySegmentResults，见 knowledgeBaseService.cjs）。2 轮后仍未覆盖的 block 会被系统强制舍弃（system_discarded_after_retry），最终生成一份报告，包含coverage_rate（覆盖率）、matched_rate（匹配率）、recovery_attempt_count等指标，并显示在最终状态消息中，例如"整理完成，共 N 条，覆盖率 X%"。

第四步：查看条目与查看 Markdown

解析完成后，文档状态变为"完成"（success），此时可打开文档进行检查：

• 查看条目：以结构化列表展示每个知识条目的标题、摘要与原文正文（readItems，对应前端openDocument(document, 'items')，见 KnowledgeBasePage.tsx）；
• 查看 Markdown：查看文档转换后的原始 Markdown（readMarkdown），适合快速确认转换质量与图片、表格是否完整保留。

在开发者模式（developer_mode配置开启）下，还可通过"分析"视图查看完整报告：候选条目数、过滤 block 数、匹配/舍弃 block 数、覆盖率等（对应 types.ts 中的KnowledgeAnalysisReport）。

第五步：解析失败的处理与重新解析

状态为"失败"（error）时，界面会显示具体错误原因。常见处理方式：

1. 根据提示修正文件后重试：例如某些 PDF 需要依赖 LibreOffice 转换，缺组件时会收到对应提示并弹出说明通知（前端通过isLibreOfficeRequiredMessage识别并展示，见 KnowledgeBasePage.tsx），按提示安装/配置解析组件后再点重试；
2. 点重试按钮：retryDocument（knowledgeBaseService.cjs）只允许对error状态的文档重试，会基于已复制的源文件从头开始解析，已完成的步骤会尽量复用；
3. 确认源文件仍在知识库目录：若返回"原始文件不存在，请重新上传"，说明源文件目录被移动或清理过，需要重新上传。

若解析过程被中断（应用异常退出等），重启后会按前文所述自动把中断文档标记为错误并提示重试，不会卡在中间状态。

全库检索：在知识库内快速定位资料

除了按文件夹浏览，知识库页面顶部还提供全库检索功能：输入关键字后，会在所有"已完成"文档的文件名、条目标题、摘要和正文中进行匹配（knowledgeBaseStore.cjs），并按"标题 > 摘要 > 正文 > 文件名"的优先级排序，返回带上下文片段（snippet）的结果。点击检索结果可直接定位到对应文档的对应条目，方便在做标书前快速回查历史资料。

让目录和正文参考已有资料：在"目录生成"中选用知识库

知识库准备好后，即可在技术方案的目录生成设置页中使用。页面上的参考知识库选择器（GenerationSettingsPage.tsx）支持：

• 按文件夹展开浏览、按关键字搜索文件夹或文档；
• 只展示状态为"完成"的文档（document.status === 'success'，见 GenerationSettingsPage.tsx）；
• 支持"全选/取消"整个文件夹，右侧面板展示"本次已选"清单，可单独移除或清空。

选中后，这些参考文档会贯穿后续生成链路：

• 目录生成：getOutlineReferences汇总所选文档的知识条目（标题 + 摘要），供目录生成任务参考（feasibilityOutlineTask.cjs）；
• 全局事实设定：globalFactsTask.cjs通过readReferences读取条目作为事实依据（globalFactsTask.cjs）；
• 正文生成：contentGenerationAgent.cjs以includeMarkdown + includeItems方式读取参考文档的正文与条目，供正文创作参考（contentGenerationAgent.cjs）。

值得注意的是，目录生成模式knowledge的描述明确说明：知识库不参与目录补充，但会用于后续全局事实和正文生成；而"保留原方案目录 + 补充评分项缺口"的模式则可"继续使用知识库增强"（见 GenerationSettingsPage.tsx）。因此建议：需要正文严格贴合历史资料风格时，务必提前在知识库中把关键资料解析为"完成"状态。

小结与最佳实践

1. 先建分类再上传：按项目或资料类型建文件夹，方便在目录生成页按文件夹批量"全选"；
2. 上传后耐心等待：超长文档会自动分段、预热缓存后并行处理，进度条是实时的，无需手动拆分文件；
3. 完成后再引用：只有状态为"完成"的文档才会出现在"参考知识库"选择器中，解析失败的文档先处理再重试；
4. 善用全库检索：写标书前用关键字检索历史资料，点击结果直达条目，避免重复造轮子；
5. 失败先看提示：LibreOffice 依赖、源文件缺失等问题都有明确文案，按提示处理并点重试即可。

关键实现文件索引：前端页面 client/src/features/knowledge-base/pages/KnowledgeBasePage.tsx、类型定义 client/src/features/knowledge-base/types.ts、解析服务 client/electron/services/knowledgeBaseService.cjs、数据存储 client/electron/services/knowledgeBaseStore.cjs、IPC 通道 client/electron/ipc/knowledgeBaseIpc.cjs。

• AI 应用
• AI 写作
• 人工智能
• AI Agent
• 企业应用