Deep Agent Skills 使用指南

Deep Agent Skills 是 KnowFlow 内置的专业任务规约，不是需要用户上传或安装的插件。选择某项能力后，系统会限制可用工具、材料范围和交付格式，让模型按对应流程完成当前任务。

使用前准备

开始前确认以下条件：

1. KnowFlow 已升级到 v2.4.9，knowflow-agent-worker 运行正常。
2. 当前聊天助理已经关联知识库。
3. 聊天模型支持原生 Tool Calling。普通文本生成正常，不代表该模型一定可以执行 Agent 工具。
4. 需要处理的文档已经完成解析；复杂 PDF 建议使用 MinerU，并按需启用 MinerU-Popo 结构增强。

一次任务怎么发起

在聊天输入框左下方点击当前回答方式，然后选择本轮要使用的能力。如果只处理几份材料，再点击“文档”，从当前助理关联且本人有权访问的知识库中选择文件。一次最多选择 100 份文档。

选择只对当前消息生效。消息发送成功后，回答方式与文档选择会恢复到会话默认值，下一轮不会沿用上一次的临时范围。

先圈定材料，再写任务要求

处理指定合同、制度或报告时，优先使用“文档”选择器。只在问题里写“根据上面的文件”，容易把材料范围说得不够明确。

深度阅读

深度阅读适合答案散落在多个章节、需要理解上下文或比较原文的任务。它会按需组合目录浏览、正文检索和节点读取，不会把 Top N 片段直接拼成结论。

可以这样提问：

比较《设备维护规范》中日常保养与年度检修的责任人、执行周期和验收要求，并列出对应原文依据。

只根据我选择的两份制度，说明异常事件从上报到关闭要经过哪些环节。两份制度有冲突时分别列出。

明确事实问题不一定要先读完整目录；涉及跨章节关系时，Agent 才会继续展开相关结构。这能减少无意义的全文翻读。

编号条款分析

当用户明确询问中文“第 X 条”的总数、最大编号、连续性、缺号或重复编号时，系统会使用专门的编号条款分析 Skill。它针对完整结构做确定性计数，而不是让模型根据检索片段估算。

推荐表达：

检查《采购管理办法》所有“第 X 条”，告诉我实际条款数、最大编号、缺号和重复编号。

目前该能力只支持“第 X 条”口径，不能把章、节、款、项混在一起统计。询问某一条的具体内容时，直接使用深度阅读即可。

结构化抽取

结构化抽取适合“每份文档一行”的记录型任务，例如合同台账、供应商资料汇总或项目申报信息整理。

一条好指令应同时说明文档范围、字段和交付格式：

从我选择的全部合同中提取合同正式名称、甲方、乙方、合同金额、签订日期、生效日期和终止日期。每份合同一行；找不到的字段留空，不要推测；最后生成 Excel。

系统会区分三种结果：

• grounded：字段值能与原文对齐；
• missing：材料中没有找到可靠值，保留为空；
• ambiguous：同一字段存在多个候选，需要用户确认。

如果要求“知识库中的全部采购合同”，Agent 可以先按条件筛选文档，再执行抽取。若要处理知识库中的每一份文档，请直接说“全部文档，无需判断文档类型”，减少不必要的资格判断。

不要让一个字段承担多个口径

“合同日期”可能指签订、生效或到期日期。字段定义含糊时，结果很难稳定。把它拆成三个字段通常更可靠。

报告生成

报告生成适合需要完整稿件的任务，包括报告、方案、文章、讲稿、通知和邮件。进入该模式后，右侧写作区会先打开，正文随后流式出现。

建议在指令中写清六件事：

1. 交付文体，例如项目复盘报告或领导讲话稿；
2. 主题；
3. 作者身份；
4. 读者或使用场景；
5. 必须保留的提纲；
6. 篇幅、语气以及是否允许使用材料外知识。

示例：

根据我选择的项目周报，写一份 2500 字左右的季度复盘，给管理层阅读。按“目标完成情况、主要问题、原因分析、下一季度安排”组织，只使用材料中的事实和数字，缺少的数据直接说明，不要补写。

短篇通常一次检索后开始写作；3000 字以上或用户给出多级提纲时，系统会先固定一次写作计划，再按章节检索和生成。正文中的引用可点击查看来源，材料里有相关图片时也可插入稿件。下载 Markdown 后，界面引用编号会被移除，正文内容保留。

智能处理

智能处理会根据本轮意图，在阅读、抽取和写作能力之间选择合适路径。任务目的清楚但不想手动判断模式时可以使用它。

对于边界很明确的任务，直接选择专业能力通常更可控。例如“生成 Excel 台账”应直接选择结构化抽取，“写一份汇报稿”应直接选择报告生成。

人工补充与任务恢复

结构化抽取遇到字段口径冲突、文档资格无法确认等关键信息时，可以暂停任务并请求补充。用户回答后，系统从当前阶段继续，不会从头重复已经完成的抽取。

补充信息时尽量一次回答全部待确认项。如果只是偏好缺失，例如没有指定标题风格，系统会采用稳妥默认值，不会为无关细节频繁打断任务。

常见问题

为什么提示模型不支持 Tool Calling？

Deep Agent 的阅读与抽取依赖原生工具调用。请在模型管理中选择明确支持 Tool Calling 的聊天模型，并确认该模型已授权给当前用户。只兼容普通对话接口的模型不能用于这些任务。

为什么出现 ModelConfigurationError？

这类错误表示 Agent Worker 没有拿到可用的租户/模型配置，或 RAGFlow Model Gateway 调用失败。依次检查当前助理的聊天模型、用户模型授权、ragflow-server 与 knowflow-agent-worker 是否使用同版本镜像，以及两端是否共享 RAGFLOW_SECRET_KEY。

为什么没有读取整个知识库？

Agent 默认受当前任务范围约束。显式选择文档后，范围会锁定到这些文件；未选择文档时，也只能在当前聊天助理关联且用户有权访问的知识库内选择来源。

为什么表格里有空值？

空值意味着没有找到与原文对齐的可靠信息。结构化抽取宁可保留缺失，也不会用常识或文件名补造字段。可以检查字段说明是否过于笼统，或确认原文是否确实包含该信息。

报告为什么没有引用材料图片？

只有解析结果中存在可用图片、当前任务允许图片且图片与正文相关时才会插入。扫描质量、解析方式和文档结构都会影响图片是否可用。复杂 PDF 可参考 MinerU-Popo 部署与配置 改善结构信息。