# 大模型与 Knowledge 知识库应用技术说明 本文档说明当前项目中大模型如何通过 Skill 与本地 Markdown 知识库协同完成领域分析。本文只覆盖当前已落地的知识库、Skill、沙箱挂载、文件读取工具和知识生成流程，不包含证据引用层、实时事件数据层或外部检索联动方案。 ## 1. 目标定位 当前 Knowledge 机制的目标不是构建传统数据库检索系统，而是为大模型提供一套可读、可路由、可组合的领域知识工作区。 它解决的问题包括： - 将台湾政治、两岸关系、美台/日台关系、选举、叙事、组织、人物、概念等长期知识沉淀为 Markdown 文件。 - 通过 Skill 告诉智能体“什么时候使用知识库、从哪里开始读、按什么顺序读”。 - 通过沙箱挂载与 `read_file` 工具，让大模型在对话过程中按需读取本地知识文件。 - 通过 routing、playbook 和具体知识档案，将知识调用从“凭模型记忆回答”转为“按知识库路径组织分析”。 简化理解： ```text 用户问题 -> 智能体判断是否适用 policy-knowledge Skill -> 读取 /mnt/knowledge/INDEX.md -> 按 routing 选择 playbook 和知识文件 -> 大模型结合用户问题与知识内容生成回答 ``` ## 2. 当前目录结构 知识相关文件主要位于： ```text 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` 挂载到智能体沙箱中： ```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`。 - 挂载是只读的，智能体可读取知识库，但不能在运行时直接修改知识库。 - 用户在本地看到的路径与智能体工具调用中的路径不同。 当前文件工具配置如下： ```yaml 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 文件位于： ```text offline-backend-20260512/backend/skills/custom/policy-knowledge/SKILL.md ``` 它的作用不是存放大量领域知识，而是给大模型提供“知识库使用规程”。核心职责包括： - 判断哪些问题应使用知识库。 - 要求智能体先读取 `/mnt/knowledge/INDEX.md`。 - 指导智能体按 `INDEX.md`、routing、playbook、具体知识文件的顺序读取。 - 约束智能体不要一次性读取整个知识库。 - 规定缺失文件、占位文件和不确定信息的降级处理方式。 - 要求回答时区分事实、解释和推论。 当前 Skill 的最小执行模板是： ```text 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/` 负责把用户问题映射到知识文件。 典型文件包括： ```text 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/` 是方法层。它告诉大模型“如何分析”，不是只告诉大模型“知道什么”。 例如： ```text 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 具体知识档案 具体知识档案按主题分散在多个目录下： ```text entities/ narratives/ events/ primitives/ policies/ reference/ data_pointers/ ``` 常见类型包括： - `entities/`：人物、组织、政党、媒体、外国行动者。 - `narratives/`：政治叙事、论述框架、社会情绪、跨海峡叙事。 - `events/`：关键历史事件或反复模式。 - `primitives/`：基础概念、分析框架、制度机制。 - `policies/`：政策领域档案。 - `reference/`：术语、暗号、地区、资料可信度等参考材料。 这些文件通常包含： - 一句话浓缩。 - 核心命题。 - 事实层。 - 脉络层。 - 与其他文件的关系。 - 常见分析陷阱。 - 仍不确定的部分。 这种格式的好处是，大模型读取文件后不仅获得事实，还获得分析边界和误区提醒。 ## 6. 智能体运行时调用流程 从技术流程看，一次知识库辅助回答大致如下： ```text 1. 用户发起问题 2. Agent 配置中包含 policy-knowledge Skill 3. 模型根据 Skill 描述判断问题适用 4. 模型调用 read_file("/mnt/knowledge/INDEX.md") 5. 模型根据 INDEX 决定读取 routing 文件 6. 模型根据 routing 选择 playbook 7. 模型根据 playbook 读取具体知识档案 8. 模型将用户问题、已读取知识和自身推理整合为回答 ``` 示例： ```text 用户：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` 工具，则会出现类似： ```text 我无法使用 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//`。 - summary JSON，记录成功、失败、token、耗时、失败 ID 等。 典型命令形态： ```bash 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 生成批次管理 每个批次建议保留： ```text runs// run_.log run_summary_.json run_.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 回答时，建议输出中体现： - 使用了哪些知识文件。 - 哪些是知识库已有判断。 - 哪些是基于用户问题做出的推论。 - 哪些部分知识库未覆盖。 - 哪些结论存在不确定性。 推荐表达方式： ```markdown 我主要参考了知识库中的： - 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 方案的核心是： ```text Skill 负责触发与使用规则 INDEX 负责入口流程 routing 负责问题到文件的映射 playbook 负责分析方法 Markdown 知识档案负责领域内容 read_file 工具负责运行时读取 generate_knowledge.py 负责批量扩展 ``` 它是一套轻量、可维护、适合本地部署的大模型知识增强机制。与传统 RAG 相比，它没有复杂检索服务，但更强调人工可读的知识组织、分析流程控制和领域推理结构。当前最适合用于稳定背景知识、结构化分析和领域任务辅助。