deerflow-code/offline-backend-20260512/backend/docs/WIKI_HIERARCHY_AND_FOCUS_GENERATION_ZH.md

Wiki 知识库参考目录与重点要求生成设计

状态：已实现，与当前代码一致 更新日期：2026-10-19

1. 目标与语义边界

创建或编辑 Wiki 知识库时提供两个互相独立的选填项：

• 参考目录：管理员或知识库所有者给出一至三级目录，帮助生成模型理解期望的信息组织方式。它不是目录白名单，也不是必须逐项套用的固定模板。
• 重点要求：用户描述允许抽取、组织和呈现的重点范围。系统把它作为严格的内容范围约束，并在生成完成后清理重点范围之外的自动生成页面。

模型可以依据原始资料新增、合并、拆分、改名、调整或省略参考目录。内容与参考目录冲突时，以资料实际内容和清晰表达为准。系统不得为了匹配参考目录预建空目录、强制移动页面、删除目录或删除参考目录之外的有效结构。

两项均可留空。全部留空时沿用 WeKnora 原有自动生成方式；原有 content_instructions 和 extraction_instructions 高级指令继续有效。本功能的权威配置全部保存在数据库，不写入 config.yaml、JSON 或其他运行时配置文件。

2. 用户交互

2.1 参考目录

前端支持两种输入格式，最多三级，不能混用。

Markdown 标题：

# 政策法规
## 国内政策
### 2026 年
## 国际规则
# 操作指南
## 申报流程

每级两个空格的缩进文本：

政策法规
  国内政策
    2026 年
  国际规则
操作指南
  申报流程

无缩进的普通逐行文本按一级参考目录处理。用户也可以下载示例文件，修改后导入 .md 或 .txt 文件。表单实时显示树形预览、节点数、规范化长度和逐行错误，并明确提示模型可以按实际资料调整结构。

2.2 重点要求

重点要求是最多 2000 个字符的自由文本，例如：

重点提取适用对象、申请条件、时间期限、审批部门和例外情形；
涉及不同年份时优先说明最新规则，并保留历史差异。

重点要求限制自动生成页面的内容范围，同时不允许模型降低事实依据要求或凭空补全资料。只填写重点、不填写参考目录时，系统保留 WeKnora 自动生成的目录结构，只过滤与重点无关的自动生成页面。

2.3 编辑语义

• 两项都支持创建后修改。
• 清空参考目录只表示不再向后续生成提供该参考，不删除或移动已经存在的远端目录和页面。
• 清空重点要求后，后续生成不再追加重点范围提示，也不再运行重点页面过滤。
• 保存时只更新请求中明确出现的 Wiki 配置字段，未出现字段保持原值。

2.4 生成后的智能检索与查看

参考目录和重点要求只影响 Wiki 的生成与整理，不要求用户在问答时重复这些指令。管理员开启普通知识库智能检索、且用户在会话中选择该模式后，用户可以直接提问；运行时先检索原始文档分片，再根据原始命中检索 Wiki 并读取相关页面，之后只针对证据缺口扩展检索。Wiki 与原始文档冲突时以原文为准。最终回答不强制输出 [1]、[2] 等编号或编号参考文献列表。

智能检索过程在执行时展开，完成后默认收起。用户展开后可以点击带稳定来源标识的 Wiki 页面或原始文档结果，在聊天页右侧来源抽屉查看详情。详情读取仍按当前用户和本地 mapping 重新鉴权。

3. API 合同

创建接口：

POST /api/llmwiki/knowledge-bases

编辑接口：

PATCH /api/llmwiki/knowledge-bases/{mapping_id}

两者的 wiki_config 使用同一结构：

{
  "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 子任务尚未结束时不提前运行重点过滤，全部结束后才清理重点范围外的自动生成页面。