Deep Agent Skills 使用指南

本文介绍 KnowFlow 内置的三项专业能力：深度阅读、结构化抽取和报告生成。它们随产品提供，无需安装。点名某项能力后，系统会限制可用工具、材料范围和交付格式，让模型按对应流程完成当前任务。

生成 Word、PowerPoint、Excel 文件的办公技能，以及管理员从技能目录安装的技能，见 办公 Agent、技能与记忆。

使用前准备

开始前确认以下条件：

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

一次任务怎么发起

v2.6.0 起，聊天输入框左下方的回答方式只有两项：

回答方式	说明
普通问答	按当前会话配置检索知识库并回答
Agent	让 Agent 读材料、判断该做什么，输入 @ 可以点名一项能力

能力、技能和文档统一在输入框里用 @ 就地点名。输入 @ 后弹出「文档和技能」菜单：

• 技能：只能选一个，包括深度阅读、结构化抽取、报告生成三项内置能力，以及管理员安装并启用的目录技能。只有 Agent 方式下才会列出。
• 文档：可多选，只列出当前会话已选知识库中、本人有权访问的文档，一轮最多 100 份。

菜单中用 ↑ / ↓ 移动，回车选中，Esc 关闭。

@ 的能力与文档只对当前消息生效。消息发送后，回答方式保留，@ 点名的能力和文档会被清空，下一轮不会沿用上一次的临时范围。切换助手会回到该助手的默认回答方式，更换知识库会清空已选文档。

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

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

深度阅读

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

可以这样提问：

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

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

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

遇到“列出所有提到某个词的地方”“某个说法出现了几次”这类问题，Agent 会改用精确匹配或正则匹配搜索文档，一次找全全部命中并给出命中数，每条命中都可以作为引用。

编号条款分析

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

推荐表达：

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

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

结构化抽取

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

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

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

系统会区分三种结果：

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

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

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

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

报告生成

报告生成适合需要完整稿件的任务，包括报告、方案、文章、讲稿、通知和邮件。点名报告生成后，右侧写作区会先打开，正文随后流式出现。v2.6.0 起写作首字从 80~90 秒降到约 2 秒。

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

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

示例：

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

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

稿件生成后可以直接修改：点击写作区的「编辑」，可改标题、章节标题和正文，改完点「保存」。正文是 Markdown，形如 [ID:数字] 的是引用标记，保留它才能在正文里显示来源。

不点名能力时

选择 Agent 方式但不 @ 任何能力时，Agent 会根据本轮意图，在阅读、抽取、写作以及已安装的技能之间选择合适路径。任务目的清楚但不想手动判断时可以这样用。（v2.4.9 中这一方式叫「智能处理」。）

对于边界很明确的任务，直接点名能力通常更可控。例如“从合同里抽字段生成台账”应 @结构化抽取，“写一份汇报稿”应 @报告生成。

人工补充与任务恢复

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

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

常见问题

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

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

为什么出现 ModelConfigurationError？

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

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

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

为什么表格里有空值？

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

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

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