deerflow-code/offline-backend-20260512/backend/knowledge/knowledge_generate/knowledge_application_technical_design.md

大模型与 Knowledge 知识库应用技术说明

本文档说明当前项目中大模型如何通过 Skill 与本地 Markdown 知识库协同完成领域分析。本文只覆盖当前已落地的知识库、Skill、沙箱挂载、文件读取工具和知识生成流程，不包含证据引用层、实时事件数据层或外部检索联动方案。

1. 目标定位

当前 Knowledge 机制的目标不是构建传统数据库检索系统，而是为大模型提供一套可读、可路由、可组合的领域知识工作区。

它解决的问题包括：

• 将台湾政治、两岸关系、美台/日台关系、选举、叙事、组织、人物、概念等长期知识沉淀为 Markdown 文件。
• 通过 Skill 告诉智能体“什么时候使用知识库、从哪里开始读、按什么顺序读”。
• 通过沙箱挂载与 read_file 工具，让大模型在对话过程中按需读取本地知识文件。
• 通过 routing、playbook 和具体知识档案，将知识调用从“凭模型记忆回答”转为“按知识库路径组织分析”。

简化理解：

用户问题
  -> 智能体判断是否适用 policy-knowledge Skill
  -> 读取 /mnt/knowledge/INDEX.md
  -> 按 routing 选择 playbook 和知识文件
  -> 大模型结合用户问题与知识内容生成回答

2. 当前目录结构

知识相关文件主要位于：

offline-backend-20260512/backend/knowledge/
  knowledge_base/
    INDEX.md
    routing/
    playbooks/
    entities/
    narratives/
    events/
    primitives/
    policies/
    reference/
    data_pointers/

  knowledge_generate/
    generate_knowledge.py
    prompts_master.json
    p1_full_list.json
    p2_full_list.json
    p3_full_list.json
    p4_full_list.json
    p5_full_list.json
    p6_full_list.json
    p_mil_ext_full_list.json
    runs/

其中：

• knowledge_base/ 是智能体运行时读取的知识库主体。
• knowledge_generate/ 是知识文件的生成与维护工具区。
• skills/custom/policy-knowledge/SKILL.md 是智能体使用知识库的入口说明。

3. 沙箱挂载与工具访问

知识库通过 config.yaml 挂载到智能体沙箱中：

sandbox:
  use: deerflow.sandbox.local.local_sandbox_provider:LocalSandboxProvider
  allow_host_bash: false
  mounts:
    - host_path: /data01/likun/deerflow-cmzs/deerflow-server/offline-backend-20260512/backend/knowledge/knowledge_base
      container_path: /mnt/knowledge
      read_only: true

这意味着：

• 宿主机路径 offline-backend-20260512/backend/knowledge/knowledge_base 在智能体视角中表现为 /mnt/knowledge。
• 挂载是只读的，智能体可读取知识库，但不能在运行时直接修改知识库。
• 用户在本地看到的路径与智能体工具调用中的路径不同。

当前文件工具配置如下：

tools:
  - name: ls
    group: filesystem
    use: deerflow.sandbox.tools:ls_tool

  - name: read_file
    group: filesystem
    use: deerflow.sandbox.tools:read_file_tool

  - name: write_file
    group: filesystem
    use: deerflow.sandbox.tools:write_file_tool

  - name: str_replace
    group: filesystem
    use: deerflow.sandbox.tools:str_replace_tool

对 Knowledge 使用来说，关键工具是：

• ls：浏览知识库目录。
• read_file：读取 INDEX.md、routing、playbook 和知识档案。

write_file 和 str_replace 主要用于输出 artifact 或编辑用户工作区文件，不应作为常规知识库写入手段，因为 /mnt/knowledge 是只读挂载。

4. Skill 的职责

policy-knowledge Skill 文件位于：

offline-backend-20260512/backend/skills/custom/policy-knowledge/SKILL.md

它的作用不是存放大量领域知识，而是给大模型提供“知识库使用规程”。核心职责包括：

• 判断哪些问题应使用知识库。
• 要求智能体先读取 /mnt/knowledge/INDEX.md。
• 指导智能体按 INDEX.md、routing、playbook、具体知识文件的顺序读取。
• 约束智能体不要一次性读取整个知识库。
• 规定缺失文件、占位文件和不确定信息的降级处理方式。
• 要求回答时区分事实、解释和推论。

当前 Skill 的最小执行模板是：

1. read_file("/mnt/knowledge/INDEX.md")
2. 根据 INDEX 读取必要规范文件
3. 读取 routing/by_question_type.md 或 routing/by_topic.md
4. 选择并读取相关 playbook
5. 按 playbook 读取具体知识文件
6. 输出结构化分析，并标注知识库覆盖范围与不确定性

5. Knowledge Base 的分层设计

当前知识库采用“入口索引 + 路由 + 分析方法 + 具体知识”的结构。

5.1 INDEX.md

INDEX.md 是知识库入口。智能体不应直接猜测要读哪些文件，而应先读取入口文件。

入口文件的作用是：

• 说明知识库整体结构。
• 规定使用流程。
• 指向 routing、playbook 和各类知识子目录。
• 帮助智能体在复杂问题中先建立读取顺序。

5.2 routing

routing/ 负责把用户问题映射到知识文件。

典型文件包括：

routing/by_question_type.md
routing/by_topic.md
routing/by_actor.md
routing/by_event.md
routing/cross_reference_rules.md

它们分别处理：

• 按问题类型路由，例如选情分析、政策信号解读、叙事归因、风险评估。
• 按主题路由，例如台湾政党、两岸关系、美台关系、日台关系、国防安全、舆论认知。
• 按行动者路由，例如 DPP、KMT、TPP、AIT、日本机构、北京相关机构。
• 按事件路由，例如大选、军演、政策宣布、司法案件。
• 多主题、多角色问题的交叉引用规则。

5.3 playbooks

playbooks/ 是方法层。它告诉大模型“如何分析”，不是只告诉大模型“知道什么”。

例如：

playbooks/analyzing_beijing_signal.md
playbooks/analyzing_us_taiwan_signals.md
playbooks/analyzing_party_strategy.md
playbooks/analyzing_vote_transfer.md
playbooks/scenario_planning_2028.md
playbooks/uncertainty_communication_protocol.md

playbook 的价值在于：

• 把分析步骤显式化。
• 降低大模型自由发挥带来的不稳定性。
• 让同类问题的回答结构更一致。
• 引导模型读取具体知识文件之前，先建立问题框架。

5.4 具体知识档案

具体知识档案按主题分散在多个目录下：

entities/
narratives/
events/
primitives/
policies/
reference/
data_pointers/

常见类型包括：

• entities/：人物、组织、政党、媒体、外国行动者。
• narratives/：政治叙事、论述框架、社会情绪、跨海峡叙事。
• events/：关键历史事件或反复模式。
• primitives/：基础概念、分析框架、制度机制。
• policies/：政策领域档案。
• reference/：术语、暗号、地区、资料可信度等参考材料。

这些文件通常包含：

• 一句话浓缩。
• 核心命题。
• 事实层。
• 脉络层。
• 与其他文件的关系。
• 常见分析陷阱。
• 仍不确定的部分。

这种格式的好处是，大模型读取文件后不仅获得事实，还获得分析边界和误区提醒。

6. 智能体运行时调用流程

从技术流程看，一次知识库辅助回答大致如下：

1. 用户发起问题
2. Agent 配置中包含 policy-knowledge Skill
3. 模型根据 Skill 描述判断问题适用
4. 模型调用 read_file("/mnt/knowledge/INDEX.md")
5. 模型根据 INDEX 决定读取 routing 文件
6. 模型根据 routing 选择 playbook
7. 模型根据 playbook 读取具体知识档案
8. 模型将用户问题、已读取知识和自身推理整合为回答

示例：

用户：2028 年台湾年轻票会怎么影响蓝绿白格局？

可能读取：
  /mnt/knowledge/INDEX.md
  /mnt/knowledge/routing/by_question_type.md
  /mnt/knowledge/routing/by_topic.md
  /mnt/knowledge/playbooks/scenario_planning_2028.md
  /mnt/knowledge/narratives/domestic/youth_political_alienation.md
  /mnt/knowledge/entities/parties/tpp_voter_base.md
  /mnt/knowledge/entities/parties/dpp_voter_base.md
  /mnt/knowledge/entities/parties/kmt_voter_base.md

最终回答不是单纯复述文件，而是把多个文件的结构性判断组合起来。

7. 与 Agent 配置的关系

知识库本身不会自动注入所有 Agent。它需要通过 Agent 的技能配置启用。

在当前系统中，Agent 可配置：

• skills
• model
• tool_groups

当某个智能体配置了 policy-knowledge，并且同时拥有 filesystem 工具组中的 read_file 能力时，它才能稳定使用知识库。

如果只配置 Skill，但没有 read_file 工具，则会出现类似：

我无法使用 read_file 工具。

这类问题不是知识库文件缺失，而是 Agent 工具权限不足。当前解决方式是在 config.yaml 中提供 read_file 工具，并在智能体工具组配置中允许使用对应工具组。

8. 知识文件生成流程

knowledge_generate/generate_knowledge.py 是批量生成知识文件的工具。

输入包括：

• prompts_master.json：通用写作规范和类型规范。
• p*_full_list.json：待生成文件清单。
• knowledge_base/：作为风格参考和关联参考的已有知识库。
• 大模型 API 配置：api-key、base-url、model。

输出包括：

• 生成后的 Markdown 文件，写入 knowledge_base/。
• 运行日志，写入 knowledge_generate/runs/<run_name>/。
• summary JSON，记录成功、失败、token、耗时、失败 ID 等。

典型命令形态：

python3 offline-backend-20260512/backend/knowledge/knowledge_generate/generate_knowledge.py \
  --api-key "$API_KEY" \
  --base-url https://api.siliconflow.cn/v1/ \
  --model Pro/zai-org/GLM-5.1 \
  --master-prompt offline-backend-20260512/backend/knowledge/knowledge_generate/prompts_master.json \
  --lists offline-backend-20260512/backend/knowledge/knowledge_generate/p6_full_list.json \
  --reference-dir offline-backend-20260512/backend/knowledge/knowledge_base \
  --output-dir offline-backend-20260512/backend/knowledge/knowledge_base \
  --priority P6 \
  --concurrency 2 \
  --max-output-tokens 12000 \
  --temperature 0.2 \
  --summary-file offline-backend-20260512/backend/knowledge/knowledge_generate/runs/p6_glm51/run_summary_p6_glm51_bg.json \
  --log-file offline-backend-20260512/backend/knowledge/knowledge_generate/runs/p6_glm51/run_p6_glm51_bg.log

生成器的关键机制：

• 从清单中读取 id、path、name、type、topic_group、must_cover、style_reference、key_relations。
• 根据 type 从 prompts_master.json 注入类型专属规范。
• 读取 style_reference 中已经存在的知识文件作为风格参考。
• 调用 OpenAI 兼容接口生成 Markdown。
• 对输出进行清理，去除代码块包裹和多余前言。
• 校验必含段落和粗略字数。
• 已存在文件默认跳过，除非指定 --overwrite。
• 支持 --ids 重跑特定失败项。

9. 当前技术优点

9.1 与大模型天然兼容

Markdown 对大模型非常友好。它既可读，又有标题层级，适合作为上下文材料注入。

9.2 不需要复杂检索服务

当前方案不依赖向量数据库或独立检索服务，部署成本低。只要 Agent 能读取 /mnt/knowledge，即可使用知识库。

9.3 可控的知识调用路径

Skill、INDEX、routing、playbook 共同约束模型行为，避免模型一次性读取过多文件，也避免完全凭模型记忆回答。

9.4 易于人工维护

知识文件是普通 Markdown，可直接人工审阅、修改、补充和 git 管理。

9.5 支持批量扩展

generate_knowledge.py 可以基于清单批量扩展知识库，适合先铺开领域覆盖面，再逐步人工校正。

10. 当前限制

10.1 依赖模型主动遵循 Skill

当前没有强制检索中间层。是否读取知识库、读哪些文件，主要由模型根据 Skill 自主决定。

如果模型没有触发 Skill，或者没有严格按 INDEX.md 工作流执行，可能仍会凭记忆回答。

10.2 缺少结构化索引

目前 routing 文件是 Markdown 规则，不是机器强约束索引。优点是可读，缺点是：

• 不方便自动计算相关性。
• 不方便做覆盖率统计。
• 不方便做路径有效性校验。

10.3 上下文窗口限制

知识文件较长时，模型不适合一次读取大量文件。当前策略依赖：

• 先读入口和 routing。
• 再读少量 playbook。
• 最后只读相关知识文件。

复杂问题仍可能遇到上下文拥挤。

10.4 质量一致性依赖生成模型

批量生成文件来自不同模型或不同批次时，可能存在：

• 结构不完全一致。
• 段落缺失。
• 分析粒度差异。
• 语言风格差异。
• 个别事实需要校验。

因此生成后的文件仍应经历抽查、修订和质量标记。

10.5 缺少自动引用校验

当前知识档案主要是分析型 Markdown，不强制要求每个事实都绑定出处。回答时可以说明来自哪个知识文件，但不能自动提供逐句来源。

11. 运维与维护建议

11.1 路径一致性检查

定期检查 routing、playbook、knowledge 文件中的交叉引用路径是否存在，避免智能体读取不存在文件。

11.2 占位文件治理

对 [占位]、空文件、低质量文件建立 audit 清单。缺失时允许智能体降级分析，但不应伪造文件内容。

11.3 生成批次管理

每个批次建议保留：

runs/<batch_name>/
  run_<batch_name>.log
  run_summary_<batch_name>.json
  run_<batch_name>.sh

这样可以追踪：

• 使用哪个模型。
• 成功/失败数量。
• token 消耗。
• 失败原因。
• 需要重跑的 ID。

11.4 Agent 能力配置检查

配置知识型智能体时至少确认：

• 已启用 policy-knowledge Skill。
• 工具组允许 read_file。
• /mnt/knowledge/INDEX.md 可读。
• config.yaml 中 knowledge_base 挂载路径正确。

11.5 人工抽检机制

对新增知识文件至少抽查：

• 标题和路径是否匹配。
• 是否有“一句话浓缩”。
• 是否覆盖 must_cover。
• 是否包含“常见的分析陷阱”和“仍不确定的部分”。
• 交叉引用路径是否存在。
• 是否存在明显事实错误或立场化表达。

12. 推荐回答规范

当智能体使用 Knowledge 回答时，建议输出中体现：

• 使用了哪些知识文件。
• 哪些是知识库已有判断。
• 哪些是基于用户问题做出的推论。
• 哪些部分知识库未覆盖。
• 哪些结论存在不确定性。

推荐表达方式：

我主要参考了知识库中的：
- narratives/domestic/youth_political_alienation.md
- entities/parties/tpp_voter_base.md
- playbooks/scenario_planning_2028.md

基于这些文件，可以把问题拆成三层：
1. 稳定结构
2. 当前变量
3. 可能情境

这样可以让用户知道回答不是凭空生成，也便于后续追问和校验。

13. 后续可扩展方向

在不改变当前主架构的情况下，后续可以逐步增强：

• 建立机器可读的 knowledge_manifest.json，记录每个知识文件的路径、类型、主题、别名和关联文件。
• 为 routing 增加自动校验脚本，发现不存在的路径。
• 增加知识文件质量评分字段，例如 draft、reviewed、needs_verification。
• 在 Agent 层增加“强制先读 INDEX”的系统提示或执行钩子，降低模型跳过知识库的概率。
• 对常见问题建立标准读取链路，例如“选情推演”“人物分析”“叙事归因”“政策信号分析”。
• 在前端展示回答所使用的知识文件列表，提升可解释性。

14. 小结

当前 Knowledge 方案的核心是：

Skill 负责触发与使用规则
INDEX 负责入口流程
routing 负责问题到文件的映射
playbook 负责分析方法
Markdown 知识档案负责领域内容
read_file 工具负责运行时读取
generate_knowledge.py 负责批量扩展

它是一套轻量、可维护、适合本地部署的大模型知识增强机制。与传统 RAG 相比，它没有复杂检索服务，但更强调人工可读的知识组织、分析流程控制和领域推理结构。当前最适合用于稳定背景知识、结构化分析和领域任务辅助。