BISHENG v2.6.0 知识空间检索能力落地工作流 / 助手应用「选择知识空间」的架构设计与实现指南【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng本文基于开源仓库 BISHENG 的 F041 featurefeatures/v2.6.0/041-knowledge-space-select-flow-assistant/系列文档编写围绕「工作流与助手应用支持选择知识空间」这一能力完整梳理其需求口径spec、设计决策design、任务拆解tasks与端到端验证e2e-checklist并结合src/backend真实源码佐证实现细节。读者读完将掌握知识空间在 4 个入口的接入方式、基于 F029 双层view_file过滤的身份切换机制、accessScope角标溯源分级方案以及完整的 25 条验收标准与 5 个开发波次的任务编排。一、Feature 定位接盘 F029 遗留项复用而非新建F041knowledge-space-select-flow-assistant是 BISHENG v2.6.0 的 P0 优先级特性核心诉求来自「首钢合入需求 §6」让工作流节点与助手应用能够把「知识空间」选为检索范围使助手 / 工作流直接利用知识空间里的内容而不必先把文件搬进普通知识库。它并非从零新建检索链路而是在既有检索链路上叠加三层能力空间 id 识别知识空间在knowledge表中是type3的行与知识库type0/1同表、id 全局唯一后端按row.type多态分派复用 F030 范式F029 双层 view_file 过滤复用KnowledgeFileVisibilityService的索引层can_read粗滤 结果层view_file精滤按身份切换由「用户知识库权限校验」开关决定过滤身份——开档用运行使用者、关档用配置者创建者。关键背景是 F029知识空间 AI 问答权限过滤曾明确将工作流 KNOWLEDGE_RETRIEVER 节点排除理由是「涉及流程节点执行上下文中的『运行用户身份』问题留待后续 feature」——F041 正是接盘该遗留项。同时它复用 F030知识资源统一对外 API「知识空间是knowledge表type3行、由后端按row.type分派」的多态检索范式。1.1 本次纳入 / 明确排除的范围纳入A–F 六块编号能力要点A知识库选择器新增独立「知识空间」tab覆盖 4 入口助手应用配置、工作流·助手节点agent、知识库问答节点rag、知识库检索节点knowledge_retrieverB两个工作流节点重命名「文档知识库问答节点」→「知识库问答节点」「文档知识库检索节点」→「知识库检索节点」仅显示名 / i18nC高级检索配置对知识空间生效默认元数据过滤仅内置字段与权限校验开关均适用于空间文件D4 入口统一「用户知识库权限校验」开关 tips助手应用、助手节点为新增开关默认关闭维持线上现状E检索结果格式与文档知识库完全一致复用统一角标溯源使用 / 展示 / 引用溯源无感知差异F角标溯源门禁与检索开关对齐方案 B 分级暴露citation 标注per_user/shared访问模式shared不整条剔除、仅按运行使用者view_file决定预览 / 下载 URL明确排除QA 知识库检索节点qa_retriever语义不同知识空间自定义元数据字段过滤F030 已确认空间无此能力OpenFGA 模型变更复用can_read/view_file不新增 ReBAC 关系个人库type2对外可选匿名 / 分享链路检索依赖登录身份对外 RPC/api/v2/filelib/retrieveF030 已覆盖临时会话文件tmptab 既有行为。1.2 三条用户故事主线故事 A配置者在知识库选择器里选独立「知识空间」tab把有权查看的空间配置为助手 / 节点检索范围故事 B运行使用者开启权限校验后检索结果只含本人有「查看」权限的空间文件无权文件的内容、文件名、来源、角标都不出现故事 C配置者 · 维持线上行为新增开关默认关闭存量助手 / 节点行为不因升级改变平滑无回归故事 D终端用户 · 溯源无差别空间来源的引用角标、来源卡片、预览跳转与文档知识库完全一致故事 E研发复用 F029 双层view_file过滤与统一 Document / citation 产出不重复实现两套检索。二、核心设计决策为什么这么实现design.md 沉淀了 8 个经过方案对比的决策其中决策 1/2/3 是本 feature 的架构脊梁。决策 1空间检索扩RagUtils注入 F029 过滤而非走aretrieve_chunks备选方案 B 是走 F030 的KnowledgeSpaceChatService.aretrieve_chunks多态检索最终选定 A——扩现有节点检索在RagUtilsrag / knowledge_retriever 节点与助手工具里识别type3空间 id → 解析空间 file_ids → 注入 F029 索引层 prefilterbuild_index_prefilter产生的 milvus_expr/es_filter到KnowledgeRetrieverTool的 search_kwargs → 结果层post_filter_visible_files精滤 → 复用既有annotate_rag_documents_with_citationscollect_rag_citation_registry_items。原因① 结果格式与 citation自动一致走同一个KnowledgeRetrieverTool → List[Document] → 同一套 annotate/collectPRD 6.3「结果格式一致」天然满足②aretrieve_chunks的空间路径只校view_space、不做 F029 双层view_file过滤也不产节点风格 citation③ blast radius 更小不动 F030 对外 RPC 语义。决策 2过滤身份按开关切换本 feature 的核心备选A 永远运行使用者、B 永远配置者、C 开运行使用者 / 关配置者。选定 C。为什么关档不能「完全不过滤」文档库「关档借整库」自洽是因为配置者对整库有权但知识空间是协作的配置者未必对全部文件有view_file若关档纯不过滤会检索到连配置者都无权看的文件——越权且抹掉空间存在的意义。C 让关档借用配置者可见范围永不越过配置者边界与文档库「借库」语义对称。实现上KnowledgeFileVisibilityService(request, login_user)的所有过滤都取构造入参self.login_user换身份换构造开档用运行使用者UserPayloadworkflowself.user_id/ assistantself.invoke_user_id关档造配置者UserPayloadUserPayload.init_login_user(user_id配置者id, tenant_id当前 flow 租户)不切换当前租户上下文。决策 3workflow 配置者 id 构造期透传备选A 像tenant_id一样把flow_user_id创建者从Workflow → GraphEngine → BaseNode透传B 节点内现查FlowDao.get_flow_by_id(self.workflow_id).user_id。选定 A——任务入口tasks.py已通过FlowDao.get_flow_by_id(workflow_id)拿到workflow_info.user_id此前只透传了tenant_id透传避免每个节点一次 DB 查询。assistant 侧无此问题AssistantAgent.assistant.user_id创建者与self.invoke_user_id运行者在实例上都直接可用。其余决策一览决策内容4前端选择器工作流节点用「模式」type新增space与 knowledge/tmp 互斥助手应用用「每项类型标记」{name, id, type:knowledge\|space}可混选回显读 type 归类存量未标记项默认按文档知识库兜底5角标溯源accessScope分级方案 Bcitation 标per_user/sharedshared分级暴露6节点改名 仅 i18n 显示名节点 type 标识rag/knowledge_retriever不变 → 存量流程零迁移7空间列表口径 client 日常模式并集/space/mine/joined/department三端点去重并集、前端一次性加载 前端名称搜索不含广场/square、不套游标分页三、任务拆解5 个 Wave、17 个任务tasks.md 将实现拆为 5 个 Wave共 17 个任务T001–T017开发模式为后端 Test-First务实版——能红-绿的先写测试检索链路重度依赖 Milvus/ES 的部分标注「测试降级手动验证 TODO」。本 feature 无新增领域对象 / 表 / 对外 API / 错误码唯一持久化 schema 改动是MessageCitation.accessScopeF029 协同T001。Wave 1 — 后端使能层无依赖可并行任务内容覆盖 ACT001accessScope字段 迁移citation/domain/schemas/citation_schema.py的CitationRegistryItemSchema加accessScope: Literal[per_user,shared] per_usercitation/domain/models/message_citation.py加持久列默认per_user从严alembic 迁移加列autogen 后手工核 DM8 兼容回滚用downgrade删列AC-19T002workflow 配置者 id 构造期透传新增flow_user_id创建者kwarg沿Workflow → GraphEngine → BaseNode透传对齐既有tenant_id节点内可读self.flow_user_idAC-14T003无副作用构造「配置者 UserPayload」UserPayload.init_login_user(...)造身份不调set_current_tenant_id不切当前租户测试test_author_userpayload_no_tenant_switch断言构造前后current_tenant_id不变AC-14T004空间检索核心辅助①SpaceFileDao.get_children_by_prefix解析空间主版本 file_ids②KnowledgeFileVisibilityService.build_index_prefilter得 milvus_expr/es_filter③ 检索后post_filter_visible_files精滤④ sync 节点经单一持久后台 looprun_async_safe范式跑 async测试覆盖 AC-12/13/14/15/24含权限变更后PermissionCacheinvalidate 的即时生效AC-12,13,14,15,16,24Wave 2 — 4 入口接检索核心任务内容覆盖 ACT005工作流 rag / knowledge_retriever 节点接空间分支RagUtils识别knowledge.typespace→ 走 T004 helper身份 开档self.user_id/ 关档self.flow_user_id空间分支产出的List[Document]复用既有 citation 组装AC-12,14,17,18,23,25T006工作流 agent 节点接空间分支 新增 user_auth 读取_init_knowledge_tools识别knowledge_id.typespace→ T004 helperAC-10,12,14,17,18T007助手应用接空间分支 新增 user_auth 读取init_knowledge_tool空间 id → T004 helper身份 开档self.invoke_user_id/ 关档self.assistant.user_idAC-10,12,14,17,18Wave 3 — 角标溯源 accessScope 分级方案 B任务内容覆盖 ACT0084 个 citation 生成点按开关赋accessScope开档/直接空间问答 →per_user关档 →shared只对空间来源分档文档库来源维持per_userAC-19T009CitationResolveService分级解析①_filter_visible_rag_itemsper_user项照 F029 按运行使用者 view_file 整条剔除、shared项不剔除②_enrich_rag_itemshared项按运行使用者 view_file 决定是否填previewUrl/downloadUrl无权→仅元数据③ 单条resolve_citation的shared无权不再抛NotFoundErrorAC-13,19,20,21,22Wave 4 — 前端手动验证任务内容T010Platform 知识空间列表 APIclient 口径新增 mine/joined/department 三端点封装 前端去重并集 名称过滤 helperT011工作流节点选择器加「知识空间」模式 tabKnowledgeSelectItem.tsx选中时typespace与 knowledge/tmp 互斥回显读 type 归类T012助手应用选择器出 tab 每项类型标记KnowledgeSelect/Setting.tsx出「文档知识库 知识空间」双 tab每条选择带 type 标记并入knowledge_list可混选T013两节点改名flow.jsoni18nnode.rag.name→知识库问答 /node.knowledge_retriever.name→知识库检索仅显示名T0144 入口统一「用户知识库权限校验」开关 tips 文案中/英/日三语助手应用、agent 节点新增开关默认关AC-11rag/knowledge_retriever 已有开关只补 tipsT015元数据过滤对知识空间只给内置字段MetadataFilter.tsx字段候选只列内置document_id/document_name/upload_time/update_time/uploader/updater不拉自定义 metadata_fields空间返回空会报错Wave 5 — 端到端 回归任务内容T016E2E 覆盖test/knowledge/test_f041_*.pyAPI 端到端 页面手动清单覆盖 25 条 AC 端到端回归T017真实环境手动验证worker 溯源起workflow_celeryworker非配置者账号触发含知识空间检索节点的工作流确认无 Event loop is closed、开/关身份过滤正确管理员在两次检索间授予/收回 view_file 验证即时生效AC-15client/workspace验证shared/per_user溯源分级四、源码级实现深挖4.1 共享检索 helperspace_flow_retrieval.pyF041 的核心新增文件是 space_flow_retrieval.py知识域供 workflow 节点与AssistantAgent共用避免 assistant→workflow 跨模块依赖。它暴露三个关键能力abuild_scoped_login_user(user_id, tenant_id)无副作用构造配置者身份。与 F030 的resolve_operator关键差异是永不调用set_current_tenant_id——workflow 节点 / 助手执行中途若切走当前租户会污染同节点后续 tenant-scoped 查询design 坑 5.10。user_id为空或用户不存在时返回None调用方按「无可见文件」处理空检索。_aretrieve_one_space单个空间的检索镜像 F029KnowledgeSpaceChatService._retrieve_and_filter的三步索引 prefilter → 2 次尝试检索 → 结果层 post_filter并 AND 合并调用方的元数据过滤AC-08。2 次尝试的 multiplier 取自visibility._config()的retrieval_initial_multiplier/retrieval_expansion_multiplierbase_k100、ef110第一次尝试有存活结果即 break。日志打点strategy / hit / kept / dropped与 F029 可观测对齐。aretrieve_space_documents跨多个空间的检索入口identity_user is None或space_ids为空 → 返回空列表AC-16 空命中不报错语义。检索完成后在每个 Document 的 metadata 上盖access_scope戳per_user/shared供下游 citation registry 持久化T008。另提供SpaceKnowledgeRetrieverToolKnowledgeRetrieverTool的 drop-in 替换与build_space_knowledge_tool供 agent 节点与 assistant 走工具路径。注意其 sync_run通过run_async_safe(self._aretrieve(query), timeout120)跳到单一持久后台 loop——绝不用asyncio.run坑 5.2每次新建 loop 会导致 OpenFGA/aiomysql 单例报 Event loop is closed节点挂。4.2 RagUtils 的空间分支在 workflow/common/knowledge.py 的RagUtils中构造时读knowledge.type新增space模式与advanced_retrieval_switch.user_auth无高级开关时回退读顶层user_auth默认Falseretrieve_question对typespace走_retrieve_space_questionsync 入口run_async_safe跑 async 过滤_aretrieve_space_docs中身份选择identity_user_id self.user_id if self._knowledge_auth else self.flow_user_id——正是决策 2 的开关分档落地access_scopeper_user if self._knowledge_auth else sharedinit_multi_retriever对 space 类型直接pass空间在aretrieve_space_documents内部按空间各自建 retriever。4.3 角标溯源分级citation_resolve_service.pyCitationResolveService 是 T009 的实现核心_apply_tier_filterweb citation 恒通过per_userRAG citation 在文件不满足view_file时整条剔除F029 现状不变sharedRAG citation关档空间来源保留——完整文件 URL 留到 enrich 阶段把关_enrich_rag_itemurl_allowedFalse时只填来源元数据documentName / knowledgeId不填previewUrl/downloadUrl与 bboxAC-21url_allowedTrue时经KnowledgeService.get_file_share_url补全 URL 与 bboxresolve_citation单条per_user 无权 → 抛NotFoundErrorAC-18 现有行为shared 无权 →保留并返回仅元数据的 enriched payloadAC-21不再抛错resolve_citations批量一次计算permitted集合同时用于过滤与 enrich 的 URL 门禁性能友好。权限解析侧_permitted_file_idslogin_user is None匿名 share 链路返回None表示「不门禁」admin 短路在post_filter_visible_files内部实现AC-24。4.4 持久化迁移两条 alembic 迁移已合入core/database/alembic/versions/v2_6_0_f046_citation_access_scope.py给message_citation加access_scope列String(16)、NOT NULL、server_defaultper_user。必须持久化而不能只进 Redis 缓存——缓存 100s TTL历史会话重开时缓存已失效走 DB若字段丢失会默认回落到per_user导致关档来源被误剔除坑 5.5v2_6_0_f047_assistant_knowledge_auth.py对应 T014 中AssistantUpdateReq.knowledge_auth的落库。五、验收标准全景AC-01 ~ AC-2525 条 AC 按 6 组组织P0 项用 EARS 句型① 选择器新增 tabAC-01~054 入口选择器出「知识空间」tab工作流节点另含临时会话文件 tab列表口径 minejoineddepartment 三端点去重并集、不含广场、无权不出现选择带类型标记持久化、回显归类助手应用支持文档库空间混选空间列表一次性加载 前端名称搜索不套游标分页。② 节点重命名AC-06~07三语显示名变更内部 type 与存量数据不变、无需迁移。③ 高级检索配置对空间生效AC-08~16本次重点AC-08/09元数据过滤支持内置字段document_id/document_name/upload_time/update_time/uploader/updater不提供自定义元数据字段AC-10/114 入口统一权限校验开关 三语 tips新增开关默认关AC-12开档仅运行使用者有view_file的主版本空间文件进结果AC-13开档时无权文件的 chunk、文件名、来源、预览链接、角标均不出现在模型上下文与回答对齐 INV-7 语义AC-14关档按配置者view_file过滤共享配置者可见范围永不越过配置者边界文档库侧沿用check_authfalse整库检索语义对称AC-15权限变更 ≤10s 生效F029 缓存 TTL 或invalidate_userAC-16检索身份对空间无任何view_file→ 空命中、不报错、不中断对话。④ 结果格式与溯源一致AC-17~19空间检索结果与文档库同构knowledge_id/document_id/document_name/chunk_index/时间/上传者等复用统一角标溯源citationId/typerag/sourcePayload每条 RAG citation 标注访问模式直接空间问答及开档来源 →per_user关档来源 →shared存量默认per_user从严。⑤ 溯源门禁分级AC-20~22per_user照 F029 整条剔除shared保留来源元数据 可点角标但无previewUrl/downloadUrl、单条 resolve 不抛NotFoundErrorshared有权或 admin返回完整溯源。⑥ 混合与边界AC-23~25空间文档库混合检索分别按各自路径过滤后合并admin/super_admin 跳过view_file过滤空间被删除/文件解析中/解析失败 → 不纳入检索、不报错。开关 tips 文案AC-10 交付物中文基准「开启后检索结果按当前使用者本人的知识空间文件查看权限过滤每人只能检索到自己有权查看的文件关闭时按配置者的可见范围检索所有使用者共享配置者能看到的文件配置者无权查看的文件同样不会被检索。文档知识库不受细粒度文件权限影响。」六、9 个已知坑 / 反直觉事实design.md §5 记录了 9 个代码里看不出的坑是本次实现最容易翻车的地方#反直觉事实后果处理5.1workflow 节点只透传运行使用者self.user_id配置者 id 没穿到节点关档取不到配置者身份过滤身份错flow_user_id透传决策 35.2节点是 Celery 线程池 sync 执行F029 过滤是 async直接asyncio.run每次新建 loop → Event loop is closed 节点挂单一持久后台 looprun_async_safe5.3空间检索必须先解析 file_idsMilvus collection 按 knowledge_id 建不先document_id in [file_ids]会搜整个空间全部文件 → 越权SpaceFileDao.get_children_by_prefix5.4空间 id 与知识库 id 同表全局唯一选择器 value 可能混着默认当 KB 处理会走错检索/权限路径前端带类型标记 后端按row.type分派5.5accessScope必须持久化到MessageCitation只进 Redis100s TTL则历史会话重开丢标记 → 关档来源被误剔除schema 持久层都加字段5.6溯源shared分级要改两处filter enrich只改 filter 会把无权用户的完整文件 URL 也发出去越权下载两处都改5.7qa_retriever节点用check_authFalse 独立qa_select_multi误改会动 QA 检索语义不碰5.8知识空间无自定义 metadata_fieldsgetKnowledgeDetailApi对空间返回空元数据过滤 UI 拉自定义字段对空间会空/报错空间 tab 只提供内置字段5.9助手KnowledgeSelect现typefile时根本不渲染 tab以为改文案就行实际要让它出 tab 结构组件改造出 tab决策 45.10resolve_operator自带set_current_tenant_id副作用为 F030 RPC 设计节点执行中途切走当前租户污染同节点后续 tenant-scoped 查询无副作用构造UserPayload沿用当前 flow 租户七、INV-7 例外与对外契约本 feature 的权限口径涉及安全不变量 INV-7 的调整它使「知识空间 AI 检索可见性 ⊆ 列表 UI 可见性」在工作流 / 助手入口成为开关可选非强制必须在 release-contract.md 中追加例外登记形式类比 F040 对 INV-6 的例外。例外同时覆盖检索侧与溯源侧开关 OFF按配置者view_file检索共享配置者可见范围、不越其边界来源 citation 标shared——溯源期不整条剔除且返回来源元数据但完整文件预览 / 下载仍按运行使用者view_file把关开关 ON按运行使用者view_file及直接空间 AI 问答入口F029维持强制语义完全不变。对外契约Outgoing四项均为加法、不破坏存量节点knowledge参数新增type:space模式user_auth出现在助手应用 / agent 节点默认 falseCitationRegistryItemSchema.accessScope默认 per_user节点显示名仅 i18n。Incoming 依赖以 F029KnowledgeFileVisibilityService按构造 login_user 决定身份是硬约束、F030resolve_operator、MessageCitation、KnowledgeRetrieverTool、SpaceFileDao.get_children_by_prefix、空间三端点 API、run_async_safe为主。八、测试与验证体系单元测试19 passing身份切换开运行使用者 / 关配置者accessScope赋值4 生成点 × 开关无副作用造配置者 UserPayloadtest_author_userpayload_no_tenant_switch。集成测试空间检索开/关两档下的view_file命中集合越权文件不进结果sharedcitation 的 enrich URL 门禁无权→无 URL、有权→有 URL历史 citation 走 DB 时 accessScope 正确。对应测试文件test_space_flow_retrieval.py、test_access_scope_tiering.py。API e2e6/6 通过test_e2e_f041_knowledge_space_select.py 覆盖可自动化的 AC-02/03/04/05/10/11。手动验证e2e-checklist.md需真实向量库 差异化权限的部分前置数据为一个空间 S含 ≥2 个解析成功的主版本文件 F_a、F_b普通用户 U 对 F_a 有view_file、对 F_b 无admin配置者对二者均可见。逐项验证选择器双 tab 与回显、节点改名三语英Knowledge Base QA / Knowledge Base Retrieval日知識ベースQA / 知識ベース検索、开关与 tips、元数据过滤仅内置字段、开档/关档检索集合、权限变更 ≤10s 即时生效、混合范围 / 管理员短路 / 异常文件、shared/per_user溯源分级、worker 无 Event loop is closed。worker 启动命令cwdsrc/backend/uv run celery -A bisheng.worker.main worker -l info -c 100 -P threads -Q workflow_celery -n workflow%h在 platform:3001建一个含知识库检索节点 选知识空间的工作流用非配置者账号触发运行观察 worker 日志无 Event loop is closed、检索结果符合开/关两档预期坑 5.2 回归 决策 2 身份切换溯源在 client/workspace用不同权限账号验证分级。可观测沿用 F029permission_filter结构化日志strategy / accessible_ids_size / post_filter_dropped_countF041 额外打点identityruntime|author与accessScope。九、实际偏差记录与后续展望已登记偏差T003/T004 的共享检索 身份 helper 落在knowledge/domain/services/space_flow_retrieval.py知识域而非 design 初稿的workflow/common/knowledge.py——原因是 assistantapi/services也要用放 workflow/common 会造成 assistant→workflow 跨模块依赖。纯实现细节未改任何决策/AC。后续不做 / 待议工作流节点内混选文档库空间本期模式互斥助手应用已支持混选知识空间自定义元数据过滤qa_retriever节点支持空间选择器是否纳入广场空间若未来aretrieve_chunks空间路径补齐view_file双层过滤 统一 citation可把决策 1 的检索入口收敛为单一多态入口。十、相关文档导航需求口径纯 Whatspec.md设计与现状快照Why this Howdesign.md任务拆解与执行落档本文主体tasks.md端到端验证清单e2e-checklist.md版本契约与 INV-7 例外登记release-contract.md前序特性029-knowledge-qa-permission-filter/spec.md复用双层过滤、030-knowledge-resource-unified-api/spec.mdtype3同表多态架构文档03-workflow-engine.md、04-knowledge-rag.md、10-permission-rbac.md【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考