dify/knowledge-fs/docs/knowledge-retrieval-v2-node-iteration-plan.md

Knowledge Retrieval v2 节点迭代计划

新增独立的 knowledge-retrieval-v2 工作流节点，对接 KnowledgeFS 知识库。与现有 knowledge-retrieval 节点（旧 dataset 体系）并存，互不混用。

需求范围

覆盖：workflow / chatflow 画布中的 KnowledgeFS 检索节点（配置、执行、试运行、发布、 运行详情展示）。

不覆盖（明确非目标）：

• Agent 应用的 dataset 工具、其他旧知识库引用面的 KFS 化。
• v1 节点的退役与自动迁移工具（仅通过输出变量结构兼容为其预留可能性）。
• 检索质量回流（workflow 空结果进 failed-query 体系）——独立立项，见"后续项"。

核心设计决策（已定）

#	决策	结论
D1	节点标识	全新 NodeType 字符串 knowledge-retrieval-v2，backend version()="1"；前端新增 BlockEnum.KnowledgeRetrievalV2。不采用 agent_v2 的同 type + version 判别模式（那是原地升级语义，本需求要求两节点并存）
D2	检索 API	网关 POST /knowledge-spaces/{id}/retrieval-tests（evidence-only），不用 createQuery（会走 LLM 生成答案，成本/延迟/语义都不符）
D3	配置归属	节点配置面保持薄：空间选择 + query 变量 + mode（+ manual metadata filters）。topK/阈值/rerank 归空间的 published retrieval profile，节点不复刻 v1 的节点级检索参数
D4	多空间	MVP 支持多空间：最多 10 个空间、最多 4 路并发检索、保留 KFS 返回的 profile-final score 做稳定降序合并并全局 topN 截断；不做每空间二次 min-max 归一化（它会把弱相关单结果错误抬到 1）。跨空间统一 rerank 留 P2，文档明示分数仅弱可比
D5	绑定生命周期	发布含 v2 节点的 workflow 时对 caller_kind=workflow 做精确同步：新增/恢复目标绑定，并撤销已从已发布 graph 移除的绑定。orphan_reconciler 当前只处理 Space 生命周期，不能替代 workflow 引用清理；admission 失败运行时报确定性错误码
D6	mode 默认值	节点默认不传 mode（每个空间分别跟随其 published defaultMode）。显式值仅允许 fast/deep/research；KFS 当前没有 auto retrieval mode，不能向该端点发送 auto。research 模式允许选择但 UI 标注高延迟高成本
D7	metadata 过滤	迭代 1 在 retrieval-tests 暴露有界的 KFS 固定字段 filters；节点 MVP 仅 manual 模式。不能复用旧 dataset 的任意 name/operator/value 条件，因为两者合同不兼容；automatic（LLM 抽条件）为 P2

开发前评审修订（2026-08-09）

原方案整体可实施，但开发以以下约束为准：

• retrieval-tests 是 evidence-only 产品操作，即使 method 为 POST，也登记为只读 action； includeText=true 只返回有界正文，不透传候选内部 metadata。
• 单候选正文最多 8,192 Unicode 字符，最多 100 个候选；产品操作响应上限 4 MiB。
• 多空间查询任一空间失败时 fail-closed，不返回容易被误认为完整结果的 partial evidence；空结果是成功。
• 多空间未显式指定 mode 时，各空间可能采用不同默认模式，因此聚合 metrics 的 mode 允许 mixed，同时返回 requested/effective mode 与 per-space 摘要，不能假设只有一个 mode。
• 草稿 debugger/explore 运行可在授权校验前幂等创建所选空间绑定；已发布/终端用户运行绝不 自动补绑定。发布路径先校验所有目标空间，再在一个事务里精确同步绑定，避免半发布状态。
• control_space_ids 最多 10 个并去重；top_n 范围 1–100；query 限 16,000 字符； filters 采用 dates/documentTypes/entities/freshnessStatuses/languages/nodeKinds/sourceIds/tags。
• DSL 跨环境不会静默接受缺失 Space：导入进入 checklist warning，发布前 validation 阻断。

现状事实（调研结论，开发前置依赖）

• 执行链路已备好：api/services/knowledge_fs/app_execution_capability.py 是 App 运行时 唯一入口（admission → capability broker 签发 → product_remote_http）， KnowledgeFSAppSpaceJoinType.WORKFLOW 已存在，create_research_task() 是完整参考实现。
• 绑定设施齐全：app_binding_management.py、orphan_reconciler.py、Console API /console/api/knowledge-fs/spaces/{id}/app-bindings（upsert/revoke/list）。
• 缺口 1：retrieval-tests 未注册进 api/knowledge-fs-product-operations.json （目前查询类只有 createQuery）。
• 缺口 2：retrieval-tests 响应 items 无证据正文（仅 nodeId/citation/score/sources）， 需网关侧新增 includeText。
• 缺口 3：retrieval-tests 请求体无 filters（KFS 管线内部支持，端点未暴露）。
• 节点注册机制：后端 NODE_TYPE_CLASSES_MAPPING（type → version → class，Node 子类自动注册）； 前端 BlockEnum + nodes/components.ts 两个 Map + workflow/constants.ts 面板列表。

---

迭代 1：网关侧——检索操作产品化（knowledge-fs 仓库，3-4 人日）

1. RetrievalTestRequestSchema 增加 includeText: boolean（默认 false）与有界 filters（结构对齐管线内部 normalizeRetrievalMetadataFilters 支持的形态，显式上限）。 响应 items 增加 text（按 maxTextCharsPerCandidate 思路截断）。 改 packages/api/src/retrieval-test-routes.ts + retrieval-test-handlers.ts + 测试。
2. Capability v2 合同登记：contracts/dify-capability-v2-operations.json 新增操作 （action queries.retrieval_test，resource knowledge_space），跑 scripts/export-capability-v2-operations.mjs，补 dify-capability-v2.test.ts 断言。 参考样例：2026-07-31 difyctl fs 命令的合同变更（同一套流程）。
3. OpenAPI 快照更新（pnpm openapi:export:test）。
4. 响应体量核算：topK(≤100) × 截断后 text 的最大字节数必须低于产品操作限额 （同类操作多为 1–4MB），超限则下调默认 text 上限。

验收：带 capability token 的 retrieval-tests 返回含 text/filters 生效的 items； 合同测试与 OpenAPI 快照绿。

迭代 2：Dify API 侧——产品操作 + 执行服务（3 人日）

1. api/knowledge-fs-product-operations.json 注册 retrieveEvidence （POST /knowledge-spaces/{id}/retrieval-tests，transport json，限额对齐核算结果）， 同步 api/knowledge-fs-contract.lock.json。
2. services/knowledge_fs/product_dto.py：KnowledgeFSRetrievalTestPayload / KnowledgeFSRetrievalTestResponse（mode/query/includeText/filters；items 含 text/citation/score/sources；metrics 摘要含 mode/totalMs/degradationFlags）。
3. app_execution_capability.py 新增 run_retrieval(run_context, caller_kind, resource, payload)，完整照 create_research_task() 模式（operation ready 检查 → issue() → execute_json → DTO 校验）。
4. 单测照 tests/.../test_knowledge_fs_capability.py、test_knowledge_fs_product_dto.py 既有模式补齐。

验收：服务层以 caller_kind=workflow 对本地 KFS 完成一次真实检索冒烟。

迭代 3：后端节点实现（4-5 人日）

新目录 api/core/workflow/nodes/knowledge_retrieval_v2/：

1. entities.py：KnowledgeRetrievalV2NodeData
   • type = "knowledge-retrieval-v2"；
   • control_space_ids: list[str]（Dify 侧 control_space_id，非上游 space uuid）；
   • query_variable_selector；
   • mode: Literal["fast","deep","research"] | None（None=各空间跟随自己的默认）；
   • top_n: int（多空间合并后截断数）；
   • metadata_filters（manual，使用 KFS 固定字段合同，不复用旧 dataset 的通用条件）。
   • 直接继承 BaseNode，不继承 LLMNode（v1 的历史包袱，v2 无 single-retrieval 模式）。
2. knowledge_retrieval_v2_node.py：version()="1"。执行：解析 query 变量 → 逐空间有界并发 run_retrieval → 保留 KFS final score 做稳定合并 + topN → 组装输出。
3. exc.py 错误分类：admission 拒绝（未绑定/权限撤销）、KFS 不可用（fail-closed 503）、 合同校验失败；检索为空不是错误。
4. 输出变量（与前端 outputVars 声明严格一致）：
   • result[]：{content, title, metadata: {citation: {document_id, document_version, section_path, page_number, start_offset, end_offset, artifact_hash}, score, sources, space_id}}。content/title 命名对齐 v1，保证下游 prompt 模板迁移成本最低；citation 为 v2 增值结构。
   • metrics：{mode, total_ms, degradation_flags}（供条件分支）。
5. 注册确认：Node 子类进 lazy registry；node_factory.py 无需特殊 init kwargs （依赖经 service 获取，不像 agent 节点注入 backend client）；工作流校验 / DSL 导入导出 对该 type 的处理路径确认。
6. 单测：mock KnowledgeFSAppExecutionCapabilityService，覆盖单/多空间、变量解析、 filters、空结果、错误路径、输出 schema。

验收：curl 构造 DSL 可跑通含 v2 节点的 workflow；single-step run 可用。

迭代 4：绑定与生命周期（2-3 人日）

1. 发布钩子：扫描 graph 中 v2 节点的 control_space_ids，逐个 app_bindings.upsert(caller_kind=WORKFLOW)；权限失败发布报错并指明空间。
2. 草稿运行 admission 语义（本迭代最高风险项，建议与迭代 2 同步定义）：draft/single-step 运行时绑定可能尚未 upsert——方案二选一：draft run 按需 upsert，或提供 preview 专用 admission 放行。定义后补集成场景验证。
3. DSL 导入/跨环境迁移：control_space_id 环境相关，导入时校验存在性，缺失进 checklist 警告（对齐 v1 对 dataset_ids 的处理），不静默保留脏引用。
4. 生命周期验证：空间删除/成员变更 → admission 拒绝 → 节点确定性错误码；确认 发布精确同步会撤销已从 graph 移除的 workflow 绑定。orphan_reconciler 只负责 Space 生命周期孤儿，不承担 app graph 引用清理。

验收：发布→运行→撤权→运行失败→恢复→运行成功全链路行为确定；草稿运行语义有测试锁定。

迭代 5：前端节点（5-6 人日，D1–D7 定稿后即可与迭代 2-4 并行，先 mock 服务层）

1. 注册：web/app/components/workflow/types.ts 增 KnowledgeRetrievalV2 = 'knowledge-retrieval-v2'；nodes/components.ts 的 NodeComponentMap/PanelComponentMap 各一行；workflow/constants.ts 面板列表（置于 v1 旁）；独立 icon（与 v1 区分配色/角标）。
2. 新目录 web/app/components/workflow/nodes/knowledge-retrieval-v2/（对照 v1 结构： default.ts / node.tsx / panel.tsx / types.ts / use-config.ts / use-single-run-form-params.ts）：
   • default.ts：metaData、默认值（mode 空）、checkValid（query 变量 + ≥1 空间）。
   • panel：空间多选（GET /console/api/knowledge-fs/spaces）、query 变量选择器（复用 VarReferencePicker）、mode 下拉（research 标注高延迟高成本）、manual metadata filters、 只读展示所选空间 retrieval profile 摘要（topK/rerank/defaultMode——传达"检索配置在 空间侧"）。
   • node.tsx：空间名 chips + mode 徽标。
3. 门控：workspace 未启用 KnowledgeFS（system-features-state.ts）时节点不出现在面板。
4. 输出变量声明与运行详情：outputVars 对齐后端；运行结果面板展示 citation （文档名 + 章节路径 + 页码）——相对 v1 的体验升级重点。
5. i18n：en-US / zh-Hans 全量 key，其余语言英文兜底。
6. Vitest：panel 交互、checkValid、use-config（按 frontend-testing 规范）。

验收：画布添加/配置/试运行/发布全通；checklist 生效；未启用 KFS 的 workspace 不可见。

迭代 6：可观测性（2 人日）

1. WorkflowNodeExecutionMetadataKey 是上游闭合枚举，不强行塞入自定义 key。mode、 totalMs、candidateCounts、degradationFlags 落节点 process_data.knowledge_fs， 同时将稳定子集作为 metrics 输出，运行详情可见且不污染全局元数据合同。
2. trace 贯通：workflow trace id 经 issue(trace_id=...) 传入，KFS 侧 metrics 可反查。

迭代 7：测试收尾与发布（3 人日）

1. 后端 integration 测试（CI-only）与前端 Vitest 全绿。当 e2e/ 具备可重置的 KnowledgeFS 服务和预置文档 fixture 后，再启用“建空间→传文档→建 workflow→ v2 节点检索→断言输出” Cucumber 场景；本期不提交无可用 fixture 的永久 skip/ 假绿场景，以 KFS route、Dify service、node 和 DSL fixture 的分层合同测试替代。
2. 含 v2 节点的 DSL 导出样例进测试 fixture，防 schema 回归。
3. 文档：节点使用文档 + v1/v2 对比表（数据源、配置归属、citation、模式差异）。
4. 发布策略：随 workspace 级 KnowledgeFS 开关走，不设独立 flag；回滚 = 关空间侧开关， 节点运行 fail-closed 报 503，错误文案给出指引。

---

依赖与并行

• 关键路径：迭代 1 → 2 → 3 → 4（合同链，串行）。
• 迭代 5 在设计决策定稿后即可并行（mock 服务层）。
• 总量约 22–26 人日；一前一后两人约三周到可发布。

风险清单（按优先级）

1. 草稿运行 admission 语义（迭代 4.2）——最易返工，提前到迭代 2 一起定义。
2. includeText 后响应体量触产品操作限额——迭代 1 内完成核算并定截断上限。
3. research 模式同步延迟——允许但默认不选，待 PageIndex research v2 落地后再放开宣传。
4. 跨空间分数合并可解释性——文档先行，避免用户拿跨空间分数做阈值分支。
5. 双节点并存的面板认知成本——命名与门控按 D1/迭代 5.3 执行；纯 greenfield 空间是否隐藏 v1 为待定产品决策，不阻塞开发。

后续项（明确不在本期）

• automatic metadata 过滤（LLM 抽取条件）。
• 跨空间统一 rerank。
• workflow 检索空结果回流 KFS failed-query 质量体系（需网关侧记录开关，独立立项）。
• v1 → v2 迁移工具与 v1 退役计划。