# Wiki 知识库参考目录与重点要求生成设计 > 状态:已实现,与当前代码一致 > 更新日期:2026-10-19 ## 1. 目标与语义边界 创建或编辑 Wiki 知识库时提供两个互相独立的选填项: - **参考目录**:管理员或知识库所有者给出一至三级目录,帮助生成模型理解期望的信息组织方式。它不是目录白名单,也不是必须逐项套用的固定模板。 - **重点要求**:用户描述允许抽取、组织和呈现的重点范围。系统把它作为严格的内容范围约束,并在生成完成后清理重点范围之外的自动生成页面。 模型可以依据原始资料新增、合并、拆分、改名、调整或省略参考目录。内容与参考目录冲突时,以资料实际内容和清晰表达为准。系统不得为了匹配参考目录预建空目录、强制移动页面、删除目录或删除参考目录之外的有效结构。 两项均可留空。全部留空时沿用 WeKnora 原有自动生成方式;原有 `content_instructions` 和 `extraction_instructions` 高级指令继续有效。本功能的权威配置全部保存在数据库,不写入 `config.yaml`、JSON 或其他运行时配置文件。 ## 2. 用户交互 ### 2.1 参考目录 前端支持两种输入格式,最多三级,不能混用。 Markdown 标题: ```markdown # 政策法规 ## 国内政策 ### 2026 年 ## 国际规则 # 操作指南 ## 申报流程 ``` 每级两个空格的缩进文本: ```text 政策法规 国内政策 2026 年 国际规则 操作指南 申报流程 ``` 无缩进的普通逐行文本按一级参考目录处理。用户也可以下载示例文件,修改后导入 `.md` 或 `.txt` 文件。表单实时显示树形预览、节点数、规范化长度和逐行错误,并明确提示模型可以按实际资料调整结构。 ### 2.2 重点要求 重点要求是最多 2000 个字符的自由文本,例如: ```text 重点提取适用对象、申请条件、时间期限、审批部门和例外情形; 涉及不同年份时优先说明最新规则,并保留历史差异。 ``` 重点要求限制自动生成页面的内容范围,同时不允许模型降低事实依据要求或凭空补全资料。只填写重点、不填写参考目录时,系统保留 WeKnora 自动生成的目录结构,只过滤与重点无关的自动生成页面。 ### 2.3 编辑语义 - 两项都支持创建后修改。 - 清空参考目录只表示不再向后续生成提供该参考,不删除或移动已经存在的远端目录和页面。 - 清空重点要求后,后续生成不再追加重点范围提示,也不再运行重点页面过滤。 - 保存时只更新请求中明确出现的 Wiki 配置字段,未出现字段保持原值。 ### 2.4 生成后的智能检索与查看 参考目录和重点要求只影响 Wiki 的生成与整理,不要求用户在问答时重复这些指令。管理员开启普通知识库智能检索、且用户在会话中选择该模式后,用户可以直接提问;运行时先检索原始文档分片,再根据原始命中检索 Wiki 并读取相关页面,之后只针对证据缺口扩展检索。Wiki 与原始文档冲突时以原文为准。最终回答不强制输出 `[1]`、`[2]` 等编号或编号参考文献列表。 智能检索过程在执行时展开,完成后默认收起。用户展开后可以点击带稳定来源标识的 Wiki 页面或原始文档结果,在聊天页右侧来源抽屉查看详情。详情读取仍按当前用户和本地 mapping 重新鉴权。 ## 3. API 合同 创建接口: ```http POST /api/llmwiki/knowledge-bases ``` 编辑接口: ```http PATCH /api/llmwiki/knowledge-bases/{mapping_id} ``` 两者的 `wiki_config` 使用同一结构: ```json { "content_instructions": "原有内容生成要求,可选", "extraction_instructions": "原有信息抽取要求,可选", "directory_paths": [ ["政策法规"], ["政策法规", "国内政策"], ["政策法规", "国内政策", "2026 年"] ], "focus_instructions": "重点说明适用对象和截止时间" } ``` `parent_directories` 作为旧版一级目录兼容字段继续接受。无论使用 `directory_paths` 还是 `parent_directories`,目录都只是生成提示中的参考结构,不能触发远端目录预建或生成后目录整理。若同一请求同时提供两个字段,两者的根目录必须完全一致;新客户端统一使用 `directory_paths`。 知识库详情响应中的 `wiki_config` 返回: - 原始内容指令、原始抽取指令; - `directory_paths`、兼容的 `parent_directories`; - `focus_instructions`; - 配置 schema、revision 和应用状态; - 参考目录提示写入 WeKnora 指令的覆盖状态及节点计数。 ## 4. 参考目录规范化与校验 前后端执行一致的基础校验,后端是最终安全边界: | 规则 | 限制 | |---|---:| | 最大深度 | 3 级 | | 最大节点数 | 100 | | 单个目录名 | 100 个字符 | | 规范化目录总长度 | 6000 个字符 | | 重点要求 | 2000 个字符 | 目录名称先执行 Unicode NFKC 规范化和首尾空白清理,并拒绝空名称、`.`、`..`、路径分隔字符、控制字符、同一父目录下的等价重复名称、跨级跳转以及非法缩进。后端将缺失的父路径自动补齐,并按父节点先于子节点的稳定顺序保存完整路径集合。 这些规则只保证参考数据能够稳定存储并安全写入提示词,不把参考目录变成业务上的硬约束。 ## 5. 有效提示编译 内容生成指令依次合并: 1. 用户原始 `content_instructions`; 2. 重点要求及“只生成直接相关且有资料支撑页面”的严格内容范围; 3. 参考目录树及“可以按资料新增、合并、拆分、改名、调整或省略目录”的软性组织指引。 信息抽取指令依次合并: 1. 用户原始 `extraction_instructions`; 2. 重点要求及“只抽取直接相关、可追溯事实”的严格内容范围。 原始指令和重点要求不会被静默截断。基础内容超过 4000 字符时返回 422。参考目录提示按父子顺序装入剩余预算;无法放入全部节点时,详情响应返回 `partial` 覆盖和实际节点数。未写入的节点仍保存在数据库中,但不执行任何本地目录补建或强制归档。 ## 6. 生成与生成后处理 ### 6.1 创建和编辑时不操作目录 创建或编辑知识库时,Gateway 只把编译后的提示传给 WeKnora,并把原始配置保存到本地数据库。无论输入来自 `directory_paths` 还是兼容字段 `parent_directories`,都不得: - 预建参考目录骨架; - 因参考目录变更而移动 Wiki 页面或文件夹; - 删除参考目录之外的文件夹、目录页或普通页面; - 周期性扫描并强制恢复参考目录。 WeKnora 生成出的目录结构就是当前资料对应的有效结构,可在后续生成中自然调整。 ### 6.2 重点范围过滤 只有非空的重点要求需要生成后协调。WeKnora 的知识库级 `is_processing` 可能早于 Wiki 生成结束变为 `false`,因此协调器还会检查每篇文档的 `pending_subtasks_count` 和 finalizing/processing 状态;确认全部结束后再执行重点判定。 重点判定遵循以下规则: - 页面主体直接提供重点所需的事实、指标、事件、关系、责任或实施细节时保留; - 只作为背景出现、与重点无关的人物、机构、地点或主题自动生成页面可以删除; - 人工维护页不因重点过滤被删除; - 判定按有界批次执行,漏项会补判,不能把“没有返回”解释成删除; - 肯定决定可按配置签名和正文指纹写入页面元数据,供相同内容重跑复用; - 所有判定完成前不做删除;判定缺项、格式非法、标记写入失败或模型不可用时,本轮不做破坏性变更; - 重点过滤始终保留 WeKnora 已生成的目录结构,不移动页面,不删除文件夹或目录页。 参考目录本身不触发 mutation-settle 或周期协调;只有重点过滤和本地 Wiki 索引同步按各自条件调度。 ## 7. 数据库存储 迁移 `20261014_02_llmwiki_generation_config.py` 在 `llmwiki_knowledge_bases` 增加: | 字段 | 用途 | |---|---| | `wiki_directory_paths` | 完整一至三级参考目录路径数组 | | `wiki_focus_instructions` | 原始重点要求 | | `wiki_content_instructions_raw` | 原始内容生成要求 | | `wiki_extraction_instructions_raw` | 原始信息抽取要求 | | `wiki_generation_managed` | 是否由当前 Wiki 配置流程管理 | | `wiki_config_schema_version` | 当前 schema 版本;参考目录语义为版本 3 | | `wiki_config_revision` | 每次有效配置变更递增 | | `wiki_config_apply_status` | `active` 或 `not_applicable` | | `wiki_config_apply_error` | 保留的应用错误字段 | 旧字段 `wiki_parent_directories` 继续保存根目录投影,兼容既有数据和旧客户端,但不保留旧的强制目录行为。SQL、内存存储与映射响应使用相同字段语义。上述生成选项、原始指令、应用状态和 revision 均以数据库记录为权威来源;前端本地状态只用于未提交表单。 后台协调器会幂等升级版本 2 的受管 Wiki:从数据库保存的原始指令、重点要求和参考目录重新编译有效提示,远端更新成功后再写入版本 3 并增加 revision;失败时保留版本 2、记录错误并稍后重试。未知版本或缺少原始配置的旧记录不会被自动覆盖。 页面级重点保留判定存放在 WeKnora 的数据库页元数据中,不使用本地文件。它只缓存某一重点版本和正文指纹下的肯定决定,不替代管理员原始配置。 ## 8. 一致性和失败处理 ### 8.1 创建 创建顺序为:校验与编译、创建 WeKnora 知识库、写入本地映射。参考目录不增加远端目录初始化步骤。WeKnora 创建成功但数据库写入失败时,系统尝试删除新建的远端知识库,避免留下无本地映射的孤儿库。 ### 8.2 编辑 编辑前读取当前远端配置和数据库原始配置: - 参考目录或指令校验失败:不修改远端和数据库; - WeKnora 更新失败:数据库保持原值; - WeKnora 更新成功但数据库提交失败:尝试恢复 WeKnora 之前的名称、描述和两段有效指令,然后把错误返回调用方。 目录参考的保存失败不会留下预建目录,因为该流程不调用远端目录创建接口。 ### 8.3 权限 沿用知识库原有授权边界:只有知识库所有者或管理员可创建和修改配置;公开浏览接口只返回调用者有权查看的内容。 ## 9. 主要实现位置 后端: - `app/gateway/wiki_generation_config.py`:重点规范化、参考目录提示与有效指令编译; - `app/gateway/wiki_directory_constraints.py`:输入规范化和重点范围过滤,不负责强制目录整理; - `app/gateway/routers/llmwiki.py`:创建、编辑、响应投影和补偿事务; - `app/gateway/llmwiki_index_scheduler.py`:重点过滤与本地 Wiki 索引的异步协调; - `packages/harness/deerflow/persistence/llmwiki/`:数据库和内存存储; - `packages/harness/deerflow/persistence/migrations/versions/20261014_02_llmwiki_generation_config.py`:数据库迁移。 前端: - `src/core/llmwiki/directory-tree.ts`:参考目录文本解析、校验和格式化; - `src/strategy-components/api/llmwiki.ts`:API 类型和请求; - `src/strategy-components/components/resource-management/llmwiki/WeKnoraKnowledgeWorkspace.tsx`:创建、编辑、示例下载、文件导入和树预览。 ## 10. 测试与验收 自动化至少覆盖: - Markdown、缩进文本、路径规范化、重复和越界校验; - 重点指令、参考目录和原始高级指令的合并、4000 字符预算和目录提示覆盖计数; - 创建与编辑会持久化参考目录,但不调用远端文件夹创建、页面移动或目录删除接口; - 新字段和兼容字段都不会启动目录协调; - 重点页面过滤、失败前不破坏及幂等重跑; - 编辑时远端失败不写本地,数据库失败恢复远端指令; - SQL/内存存储字段往返、迁移单头和迁移兼容性; - 前端参考目录解析、示例文件和生产构建。 验收时至少使用下列组合: 1. 两项均为空,行为与原有 Wiki 创建一致; 2. 只给参考目录,模型可以采用、补充、合并或调整目录,系统不创建固定骨架,也不移动或删除生成结构; 3. 只给重点要求,只保留重点范围内且有来源依据的自动生成页面,同时目录保持不变; 4. 两项同时填写,参考目录提供组织方向,重点范围独立生效; 5. 使用兼容字段 `parent_directories` 创建或编辑,仍然只有参考语义; 6. 编辑后 revision 增加,刷新页面仍从数据库恢复原始配置; 7. 清空参考目录后不再向后续生成提供参考,已有目录和内容不被删除或移动; 8. 重启服务或更换浏览器后,参考目录、重点要求、原始指令和 revision 仍从数据库恢复; 9. 生成后的 Wiki 页面可进入智能检索,并可在右侧抽屉查看来源详情; 10. 文档 Wiki 子任务尚未结束时不提前运行重点过滤,全部结束后才清理重点范围外的自动生成页面。