description: "在一个 profile 层中管理知识库、文档、Wiki、FAQ、数据源并提供 Agent 知识工具。" kind: "package-bundle"

@gestaltrun/dsh-knowledge

English | 中文

概要

管理个人与组织空间的知识库，浏览文档与 Wiki 页面，导入 FAQ 并配置数据源。Agent 通过知识工具检索并引用同一当前空间。此包将这些功能放在一个可选 Desktop profile 层中，并依赖商家账号包。

目录

• 使用此包
• 了解实现
• 模型体验
• 已知限制和后续工作
• 开发备注

使用此包

Desktop 产品组合 在 @gestaltrun/dsh-merchant-account 后选择此可选 bundle。包的 patch 只插入 gestaltrun-knowledge → @gestaltrun/dsh-knowledge；根入口挂载知识 Remote 与工具，Client 入口挂载页面、面板和工具卡片。账号领域作为外部 peer，源码兼容范围为 ^0.1.1；workspace:* 是开发依赖，不证明 npm 已发布。正式发布前必须已有兼容的账号包发布版本。

先用 pnpm --dir product run build:merchant-api 构建账号 Host/Client，再运行 pnpm --dir product run build:knowledge 和 pnpm --dir product run smoke:knowledge。知识构建生成 Host、Typert Remote 和 Client 产物；smoke 用真实 Loader 加载单行，检查 Remote 方法标识、完整工具卡片键集合、Client 注册和 Host/Client 卸载完成。Client factory 使用已发布的 React 和 store 模块；归档图标只用注册替身，未声明的模块会令 smoke 失败。Registry 安装与真实服务端/模型行为需要另行提供发布和验收证据。

公开入口为 .、./client、./types、./api、./tools、./typert、./remote、./package.json 和 ./locale/*.json。Remote namespace 为 knowledge，Host 服务为 knowledgeApi，生成的调用 id 以 @gestaltrun/dsh-knowledge#knowledge/ 开头。默认工具名仍为 mcp__knowledge__*。locale namespace 仍为 gestaltrun.knowledge 与 gestaltrun.knowledgeTools。主页面/侧栏 id 与 dock kind 仍为 gestaltrun-knowledge；dock key 保留 @gestaltrun/dsh-ui-knowledge/dock 与 /source。localStorage 键仍为 gestaltrun.knowledge.pinned 与 gestaltrun.knowledge.recently-opened。

了解实现

Layout

Client 入口注册 gestaltrun.knowledge 文案命名空间、main 页面 gestaltrun-knowledge、账号登录期间同 id 的 sidebar.panellist 入口（会话结束时关闭打开的页面），以及右侧边栏 dock 页签类型 gestaltrun-knowledge 与其窗格主体。侧边栏顺序为 -40，位于客服托管之后、组织与成员、自动化任务和插件之前。src/client/weknora/ 存放下述 WeKnora 移植模块；所有视图用 React 基于 DSH ui-primitives 重写。

Scope and permissions

空间跟随商家账号，规则与账号菜单相同。淘宝账号列出个人使用与可切换的全部组织；店铺账号只列出自己的店铺，没有个人一行。切换调用账号的组织切换；ctx.knowledge 自行跟随新空间。组织内管理员可新建、复制、删除与修改设置；成员看到成员说明、无新建入口、无复制或删除操作，设置页签只读。个人使用拥有全部权限。置顶对成员仍然可用：它是该用户的本地标记，不是对知识库的修改。

List

卡片显示名称、类型、能力标记（Wiki、知识图谱、多模态、问题生成）、文档数、解析与失败数、未完成初始化标记和相对更新时间；分组为 置顶、最近使用 与 全部。「最近使用」不包含已置顶的知识库。搜索匹配名称与描述。模型未配置的知识库触发「未完成初始化」提示条并点名，附前往设置的快捷入口。卡片菜单对所有人提供设置与置顶，对管理员或个人使用再提供复制与删除确认。复制创建保留源库设置与能力标记的空副本，然后重新读取列表，不复制知识内容。加载显示骨架卡片，失败的刷新保留上一个值并可重试，每个空状态都说明下一步。置顶与最近使用是按用户和空间保存在 Client 本地的记录（pinned.ts、recently-opened.ts）。列表忽略知识库应答上的 isPinned，因为上游置顶会被所有能看到该知识库的人共享。WeKnora 不报告最近打开时间。

Creation

对话框先选择类型——文档库 或 问答库——再填写基本信息：名称（必填，至多 200 字）与可选描述（至多 4000 字）。两个上限按 UTF-16 单元计数，与服务端一致；补充字符占两个单元。被拒绝时对话框保持打开并保留草稿。名称与描述校验错误显示在对应输入旁，标记输入无效，并在该字段修改后清除；其他失败显示分类后的失败文案；创建成功后打开该知识库的页面；列表刷新完成前，新库已立即加入列表和总数。对话框复用设置编辑器；名称为空时在离开输入框或提交后提示。AI 生成描述单独显示结果卡片，包含摘要、标签、典型问题和生成时间；只有点击「用作知识库描述」才填入描述草稿，保存后写入知识库。

Base page and dock

知识库页面承载带能力标记的头部与页签条——文档、问答、Wiki、图谱、检索测试、数据源、活动、图片、设置（问答库隐藏 文档，成员看不到 活动）。文档页签以表格或卡片列出文档，按名称、标签、解析状态与排序筛选，并通过文件夹菜单、面包屑和子文件夹磁贴浏览目录。问答、检索测试、数据源、活动、图片、图谱、设置 各自渲染页面。图谱 显示 Wiki 页面之间的链接图：概览、按类型筛选、适应视图、箭头、展开邻居，以及返回概览。设置 对管理员是完整编辑器，对成员只读。dock 页签是对话旁知识面板。它在当前空间检索 Wiki 页面、已解析的文档分块和文档。分组显示条数，命中词高亮，每行都提供引用操作。注入 searchKnowledge 时，命中显示服务端的匹配方式与得分。知识库筛选占一行，可横向滚动。绿色空间状态点显示组织名称与角色，或“个人空间”；来源阅读器在切换空间后重新读取。「在对话旁打开」切换到对话并在会话挂载后打开该页签。

活动详情在右侧抽屉打开，支持 Esc、遮罩关闭、焦点限制与返回触发按钮。只展示记录提供的变更、任务字段和导入计数，不推断缺失值。接口提供 JSON 前后值时显示记录值，脱敏值保持隐藏。

上传确认的图片描述语言可选中文、英语或沿用知识库设置。明确选择的语言只作用于本批上传；沿用时使用知识库的描述语言。「上传位置」选择目标文件夹；上传文件夹保留嵌套目录。图片属性说明显示在开关右侧。

新建和编辑手写文档在保存成功前保留标题和 Markdown。标题不能为空且最多 1024 个字符，导入 URL 最多 2048 个字符。服务端字段错误显示在对应输入旁。批量标签、批量移动和单文档移动失败后保留表单与文档选择。跨知识库移动可选复用向量或按目标配置重新解析。

标签管理从右侧打开，左侧文档表仍可见。打开时读取最新计数，批量打标签成功后刷新计数。标签有颜色点，成功和错误提示使用对应颜色。文档失败原因单行截断，悬停显示完整本地化说明。疑似卡住的文档使用警告色。打开的知识库页头每五秒读取不受筛选影响的文档总数，包含后台同步新增的文档。

Vendored WeKnora modules

src/client/weknora/ 携带从 WeKnora commit 60a7be32d8a9a6bd9961b91ba69f0dac4ab90da3 复制的 API 类型、与框架无关的逻辑模块和数据源图标（MIT；见 src/client/weknora/LICENSE.WeKnora）；每个文件头部注明上游路径。数据源页签使用 datasourceIcons 和复制来的图标。页面卡片读取知识 API 视图。文档页签用 documentSorting 提供排序取值，用 folderTree 处理文件夹路径。知识功能的 zh-CN 文案并入本包的 locale 字典，而非作为移植的 i18n 模块保留。

Contract source

server 的知识库代理契约尚未发布，因此本包在 src/api/routes.ts 中按账号 Provider 发送所用的 MerchantRouteDefinition 定义路由，路径与请求体跟随 server 契约（gestaltrun/gestalt-travel-server 里程碑 PR #63）：代理把上游 /api/v1/knowledge-bases… 映射为个人使用的 /v1/knowledge/bases… 和组织内的 /v1/tenants/{tenantId}/knowledge/bases…，请求体保持上游原样。正式知识 release 快照必须在发布前提供这些路由，与账号和资源快照分开。

列表应答保留 WeKnora 的 { success, data } 信封；schema 只保留 Client 读取的字段，丢弃未知的上游字段。创建应答是代理取出 data 后的裸知识库对象。复制走 POST …/bases/copy，正文为 { sourceId, targetId?, taskId? }，应答保留信封中的 data.task_id、data.source_id 与 data.target_id。复制进度走 GET …/bases/copy/progress/{taskId}。删除走 DELETE …/bases/{knowledgeBaseId}，应答只校验 success 信封。文档列表走 GET …/bases/{knowledgeBaseId}/documents，信封是扁平的 { success, data, total, page, page_size }。未打标签的文档 tags 为 null，视图转成空列表，parse_status 为 draft 时保留。查询转发 page、page_size、keyword、tag_ids、parse_status、sort_by、sort_order、folder_path 与 folder_recursive，空的关键词或标签列表会被省略。标签列表走 GET …/bases/{knowledgeBaseId}/tags，信封是嵌套的 { success, data: { total, page, page_size, data } }。成员可以读取这两项。新建标签走 POST …/bases/{knowledgeBaseId}/tags，正文为 { name }。重命名走 PUT …/bases/{knowledgeBaseId}/tags/{tagId}，正文为 { name }。删除走 DELETE …/bases/{knowledgeBaseId}/tags/{tagId}，不发送 force 与 content_only：仍被文档使用的标签会被拒绝，那些文档会保留。成员可以新建、重命名和删除标签。文件上传走 POST …/bases/{knowledgeBaseId}/file。Client 在 knowledge/uploadFile 上以 base64 发送文件字节；Host 重新组装原始 multipart 正文，并转发该 Content-Type。multipart 的 process_config 发送 summary_enabled、enable_multimodel 与 image_attrs_enabled，并且不发送 vlm_config，这样知识库会保留自己的 VLM 模型。网址导入走 POST …/bases/{knowledgeBaseId}/url，正文是 JSON。手写 Markdown 走 POST …/bases/{knowledgeBaseId}/manual，正文是 JSON，调用方设置 status 时一并发送。publish 进入解析；省略 status 则保持 draft。成员可以执行这三项写入。网址和手写正文没有 folder_path；目标文件夹由随后的移动完成。文档与标签路径跟随 server 分支的 knowledge-documents.ts（GET …/documents，不是上游的 /knowledge 段）。文件夹列表走 GET …/bases/{knowledgeBaseId}/folders，应答为 { success, data: { root_document_count, total_document_count, folders } }。重命名、移动或合并文件夹走 PUT …/bases/{knowledgeBaseId}/folders，正文为 { from, to }；目标路径已存在时 WeKnora 合并，且不能把文件夹移入自身的子目录。成员可以读取并重命名文件夹。按 id 读取文档走 GET …/documents/batch，ids 为 1 到 200 个 id 的逗号分隔列表，并带 kb_id；该 { success, data } 应答填写文档列表所省略的 stall_state。成员可以读取它。替换标签走 PUT …/documents/tags，正文为 { updates, kb_id }，每项更新替换该文档的标签。移入文件夹走 POST …/documents/folder，正文为 { kb_id, knowledge_ids, folder_path }；空的 folder_path 表示根目录并且会发送。重新解析走 POST …/documents/batch-reparse，正文为 { kb_id, ids }，并省略 process_config。删除走 POST …/documents/batch-delete，正文为 { kb_id, ids }。成员可以执行这些写入。移入另一个知识库走 POST …/documents/move，正文为 { knowledge_ids, source_kb_id, target_kb_id, mode }，组织内需要管理员。可移入的知识库走 GET …/bases/{knowledgeBaseId}/move-targets。ZIP 走 POST …/bases/{knowledgeBaseId}/batch-download，正文为 { ids }（1 到 200 个）；应答正文是压缩包，服务端会省略没有原始文件的条目，正文中没有跳过计数。单篇文档走 GET …/documents/{knowledgeId}，手写 Markdown 从 metadata 读取。下载走 GET …/documents/{knowledgeId}/download，预览走 GET …/documents/{knowledgeId}/preview，两者的应答正文都是文件字节。处理轨迹走 GET …/documents/{knowledgeId}/stages。替换手写 Markdown 走 PUT …/documents/{knowledgeId}/manual，同样转发 status。重新解析单篇走 POST …/documents/{knowledgeId}/reparse，正文为 {}。停止解析走 POST …/documents/{knowledgeId}/cancel-parse。删除单篇走 DELETE …/documents/{knowledgeId}。成员可以执行这些调用。在该契约以快照发布之前，本包仍在本地定义这些路由。置顶不是被代理的操作。

Remote namespace

Host 入口导出 name 与 apply；apply 加载等待 merchantAccount 的 KnowledgeApi。每个方法都指明作用空间：knowledge/listBases 列出一个空间的知识库，knowledge/createBase 在其中创建（组织内需管理员，个人使用均可），knowledge/copyBase 开始一次内容复制（组织内需管理员），knowledge/copyProgress 读取该任务（成员可读），knowledge/deleteBase 删除一个知识库（组织内需管理员），knowledge/listDocuments 列出一个知识库的文档，knowledge/listTags 列出它的标签，knowledge/createTag 新建标签，knowledge/updateTag 重命名标签，knowledge/deleteTag 以代理要求的 JSON {} 正文删除未被使用的标签；省略 force 和 content_only 查询参数以及可选的 exclude_ids 正文字段。knowledge/detachDeleteTag 先从带有该标签的每篇文档上移除它，包含子文件夹中的文档，每批最多 200 篇，然后删除标签。它从不发送 force 或 content_only。KnowledgeTagDetachDeleteResult 结果中的篇数只计入成功返回的批次中已确认的文档。失败时返回阶段；当前写入可能已生效时标记 unconfirmed，整次调用结果未知时 detached 为 null。该操作不删除文档。每批更新保留该批读取到的其他标签；同一篇文档上并发新增的标签可能被覆盖。knowledge/uploadFile 上传一个文件，knowledge/importUrl 导入一个网址，knowledge/createManual 创建手写 Markdown，knowledge/listFolders 列出它的文件夹，knowledge/readDocuments 按 id 读取文档并填写卡住状态，knowledge/renameFolder 重命名、移动或合并一个文件夹。knowledge/tagDocuments 替换文档标签，knowledge/moveToFolder 把文档移入文件夹，knowledge/reparseDocuments 重新解析文档，knowledge/deleteDocuments 删除文档；成员可以执行这些写入。knowledge/listMoveTargets 列出可以接收文档的知识库。knowledge/moveDocuments 把文档移入另一个知识库，组织内需要管理员。knowledge/downloadDocuments 返回 POST …/bases/{knowledgeBaseId}/batch-download 的 ZIP 字节。knowledge/readDocument 读取一篇文档，knowledge/readStages 读取它的处理轨迹，knowledge/downloadFile 与 knowledge/previewFile 返回单个文件的字节，knowledge/updateManual 替换手写 Markdown，knowledge/reparseDocument 重新解析一篇文档，knowledge/cancelParse 停止一次解析，knowledge/deleteDocument 删除一篇文档。成员可以执行这些调用。成员可以读取文档、标签、文件夹、卡住状态和可移入的知识库，也可以重命名文件夹。会话当前组织与请求组织不一致时，组织路由应答空间问题，账号状态随后给出应显示的空间。copyBase 在调用方未提供 taskId 时省略该字段：WeKnora 会拒绝不含上游租户号的调用方任务号，而本包没有该租户号，分配到的任务号在 data.task_id 中返回。

请求失败转换为商家账号的类型化远程错误：merchant/unreachable；merchant/server（含 HTTP 状态、契约 code，且 NO_CURRENT_TENANT、TENANT_NOT_CURRENT、NOT_A_MEMBER、KNOWLEDGE_PERSONAL_USE_REQUIRED 时 tenantContext 为真）；merchant/contract；merchant/signed-out；merchant/no-current-tenant。

视图携带知识库卡片与详情头部所需内容：id、名称、类型、描述、能力标记（Wiki、知识图谱、多模态、问题生成）、数量、置顶状态与时间。必配模型缺失时 initialized 为假，列表以「未完成初始化」提示条显示；列表带 failed_count 时 failedCount 取该值，列表省略该字段时为 null。

设置读取保留库详情里非空的模型 id。生成模型为空时使用 config.llm.modelId，视觉模型为空时使用 config.multimodal.vlm.modelId；配置中的显示名称进入可选的 summaryModelName、embeddingModelName 和 vlm.modelName 字段。空名称和 UUID 不进入这些字段。显示名称不作为 id，也不进入两种更新请求。保存将生成模型写为 llmModelId，视觉模型写为 vlm_config.model_id 并带上 multimodal.enabled，完整的抽取规则写为 nodeExtract。示例文本生成和试运行抽取使用同一生成模型。

文件、网址和 Markdown 上传将明确选择的描述语言写入 process_config.vlm_config.description_language。Host 读取有效视觉配置，在覆盖中保留模型 id、启用标记和自定义指令。auto 省略 VLM 覆盖，沿用知识库设置。上传不修改这些设置。

画廊图片将上游 attrs 映射保留为 attributes，包括 false、零、null 和结构化 JSON 值。缺失或 null 的映射保持缺失。列表提供不透明分块 id，但没有来源分块序号；消费方不能编造来源位置。

详情读取将 generated_profile 投影为只读的 generatedProfile，包含 gist、topics、typicalQuestions 和 generatedAt；生成命令返回相同的简介字段。手写 description 单独保留，两种设置更新都不序列化生成的简介。

Client object

./client 入口挂载生成的命名空间并提供注入 merchant Client 对象的 ctx.knowledge。ctx.knowledge.bases 跟随账号流：登录且身份已到达时，它为当前空间——组织或个人使用——保持一个读取器；切换空间会释放旧读取器并新建一个。未登录时状态为 signed-out，命令应答 signed-out 失败；身份到达前不发起读取，店铺账号因此不会先读到个人列表。读取器只发布最新开始的一次读取，失败的刷新保留上一个值，创建或删除成功后重新读取，释放后不再发布。copy 与 copyProgress 不读取列表：新库在任务完成时出现，页面到那时再读取列表。listDocuments、readDocuments、listTags、createTag、updateTag、deleteTag、detachDeleteTag、uploadFile、importUrl、createManual、listFolders、renameFolder、tagDocuments、moveToFolder、moveDocuments、reparseDocuments、deleteDocuments、listMoveTargets、downloadDocuments、readDocument、readStages、downloadFile、previewFile、updateManual、reparseDocument、cancelParse 与 deleteDocument 同样不读取列表。create、copy、copyProgress、remove、listDocuments、readDocuments、listTags、createTag、updateTag、deleteTag、detachDeleteTag、uploadFile、importUrl、createManual、listFolders、renameFolder、tagDocuments、moveToFolder、moveDocuments、reparseDocuments、deleteDocuments、listMoveTargets、downloadDocuments、readDocument、readStages、downloadFile、previewFile、updateManual、reparseDocument、cancelParse、deleteDocument 经当前读取器执行。

活动读取返回 actorMember/sourceType 与顶层或 details.changes 的完整 changes，保留 JSON 前后值、redacted 和旧 change。分块及 Wiki 修订返回 editorMember/editorSourceType。Wiki 更新发送独立的 editSummary，修订保留 editSummary/aliases，问题返回 reportedAt。画廊 chunkNumber/imageNumber 取上游零基索引加一，缺索引时保持缺省。Wiki 活动保留页面标题、targetSlug 和页面 targetId。数据源返回 retainedKnowledgeCount（缺失时为 null）。listModels() 读取当前空间的 conversation、summary、vision、wiki、embedding 可选模型目录，各项含 id/name/displayName。readFaqImportFailures({ taskId, limit?, offset? }) 返回 entries[{ rowNumber, reasonCode, reason, rawEntry }] 与 total，只通过服务端授权的固定 JSON 路径读取。

Proxy connection

server 的知识契约（gestalt-travel-server PR #63）把 MCP 端点暴露为两条路由：个人使用的 POST /v1/knowledge/mcp 与组织的 POST /v1/tenants/{tenantId}/knowledge/mcp，每条携带一个 JSON-RPC 请求并返回端点的 JSON。src/proxy-transport.ts 构造 MCP SDK Streamable HTTP 传输所用的 fetch：POST 按当前空间选路，变成一次商家会话请求；通知（没有 id 的消息）在本地以 202 应答（无状态代理总是回答一个 JSON 对象，表达不了通知应得的空 202）；GET/DELETE 以 405 应答（没有服务端到客户端的流，也没有会话可终止）。src/connection.ts 跟随账号状态：已登录且有身份时进行 initialize/tools/list 握手（有界退避重试）；退出登录或身份缺失时关闭连接并注销工具。每个 POST 都重新解析空间，因此切换空间无需重连——下一次工具调用自然走新空间的代理路径。

连接复用 @deepseek-ai/dsh-mcp-client 的 createMcpToolDefinition 保持 MCP 结果契约：规范值 content/structuredContent、线上使用原始工具名、MCP isError 映射为工具失败。

Space recording

src/tools.ts 包装每个 MCP 工具定义：执行器在原始调用回调里（即实际交换发生处）解析空间，并把它嵌入规范值 { space, user, content, structuredContent? }。模型可见文本以 知识库空间：<名称> 起头，output.presentationMeta 从同一个值投影可重放的工具卡片事实——工具、空间、用户、查询、摘要，以及带 kb:/doc:/chunk:/wiki: 引用的命中来源。渲染内容与 meta 都持久化在 tool/result 上，会话日志因此既能重建模型看到的内容，也能重建卡片显示的内容，包括每次调用所用空间。投影（src/presentation.ts）是纯函数且有界：每张卡片至多 20 条命中、160 字符摘要片段、200 字符行。<search_results> 应答与带 display_type 的 JSON 文档走同一条投影：每个 <page> 是一条 Wiki 命中（wiki:<slug>），每个 <chunk> 是一条分块命中。

MCP 与传输失败保留失败状态，在 meta 中记录已捕获的空间与用户，并在模型可见文本中使用相同的空间前缀。解析出空间之前的失败没有可记录的空间。read_document 缺少来源知识库 id 时，执行器通过已捕获空间的商家路由读取文档详情，把 knowledgeBaseId 保存到规范值；卡片投影据此重新打开对应文档与分块。

Tool whitelist

src/whitelist.ts 是 server 代理的工具清单去掉 ask：list_knowledge_bases、search_knowledge、grep_chunks、list_documents、read_document、add_document、update_document、delete_document、wiki_search、wiki_read_page、wiki_index、wiki_write_page、wiki_replace_text、wiki_rename_page、wiki_delete_page、wiki_read_issues、wiki_update_issue、query_knowledge_graph。tools/list 里白名单之外的条目——上游新增的工具或误配了 ask 的端点——会被跳过并记录日志。

Tool cards

Client 入口按白名单内每个工具的公开名字注册一个 keyed tool.call.toolview，使用本包的 locale 命名空间。调用进行中，卡片显示工具标题和从原始参数推导的查询行（与 Host 同一套纯投影）；结果落地后，卡片读取持久化的 presentationMeta——浅蓝信息标签形式的空间、摘要、带 kb:/doc:/chunk:/wiki: ref 的命中来源——并在本地校验该 wire 值，格式不对时回退到参数推导的事实。点击命中来源会切换到已有来源页签，未打开时才新开以来源命名的页签。图谱页签使用来源文档的标题。空间或会话切换、插件卸载后，未完成的图谱来源打开操作不再打开页签。检索命中行显示文档名和分块编号、知识库名称与得分。已记录结果缺少编号时，Client 读取当前空间的分块位置。阅读、列表和 Wiki 写入不显示排名得分；无法匹配名称的知识库 id 使用通用知识库标签。列表卡片显示总数，Wiki 阅读显示返回或已记录的版本和正文字数。失败卡片只显示原因，不重复模型文本中的空间前缀；日志文本保持不变。阅读文档的查询行显示文档标题。图谱命中从已记录结果显示不重复的实体—关系—实体三元组。工具失败时，即使缺少展示元数据，仍保留错误卡片。在折叠对话模式中，展开已完成轮次后，还需展开工具处理分组才能看到卡片；两层折叠互相独立。图抽取关闭时，失败的知识图谱查询写明该知识库没有开启知识图谱。

Configuration

serverName（默认 knowledge，须匹配 [A-Za-z0-9_-]{1,32}）命名公开工具名，toolCallTimeoutMs（默认 60000，至少 1）限定一次 tools/call。Schemastery 在 cordis.yml 里校验两者，resolveConfig 为编程构造重新判定边界，配置错误使插件实例在加载时失败。

模型体验

已登录且有身份时注册白名单内的 WeKnora 工具；退出登录后注销。每个结果的模型可见文本带一行开头标明知识空间，每个工具结果持久化卡片 meta（空间、用户、查询、命中）。不新增提示词段落或 Session 事件；工具经普通注册表参与提示组装。

已知限制和后续工作

正式知识服务端契约产物尚未提供。发布和生产 Desktop 门禁要求 src/contract/ 中完整且来源为 release 的知识快照，并满足生产服务端版本与最低 Client 版本。check-merchant-contract-release 检查独立知识快照；缺失产物时失败。候选构建、源码契约测试和 workspace peer 均不能代替正式产物。真实发布由用户通过 product-v* 执行；默认发布列表不加入知识包。

• 图谱 显示 Wiki 页面之间的链接图：概览、按类型筛选、适应视图、箭头、展开邻居，以及返回概览。在 Wiki 页面上，「在图谱中查看」打开该页签并定位到该页。问答、检索测试、数据源、活动、图片、设置 有各自的页面。文档页列出、搜索、筛选并浏览文件夹。空文件夹只存在于该页，直到有文档被移入；仍有文档的文件夹拒绝删除。每篇文档可以查看；文件和手写 Markdown 可以下载和预览。手写 Markdown 可以编辑。单篇可以移动、重新解析、停止解析、查看处理轨迹并删除。标签抽屉可以新建、重命名和删除标签。删除仍被文档使用的标签时，会先从这些文档上移除该标签，包括子文件夹中的文档，并保留文档；并发标签写入可能覆盖其他标签。确认框说明文档会保留。成功时提示标签已删除。失败时说明失败阶段及已确认篇数或不确定状态；重试会重新列出文档。若删除因标签仍被使用而被拒绝，标签保留，并且可以重试。成员可以上传文件或文件夹、从网址导入，以及编写 Markdown。保存新建或编辑后的 Markdown 会发送 status publish，文档因此进入解析。上传确认框列出文件名和大小，标出同名文件，预选已选文档的共有标签，并通过标签芯片和开关设置目标位置、标签与本批解析选项。客户端任务面板以分段进度条显示已完成、进行中、等待、失败与已跳过数量。已加载的文档和批量状态读取同步任务面板；finalizing 阶段的文档已可检索，面板计为已完成。上传错误显示本地化原因，不显示内部错误码。任务面板和文档行显示已知解析失败的具体原因，包括文件损坏或格式无法识别；未知失败使用通用重试提示。文档操作结果使用页面共享的提示条，切换页签后仍保留。新建、上传和删除刷新知识库列表；标签、文件夹移动和解析操作刷新对应文档视图。页面头部显示服务端返回的整个知识库文档总数，包含所有文件夹，不随搜索、标签或状态筛选变化。已加载的选择可以设置标签、移入文件夹或另一个知识库、下载最多 200 个文档且已知文件大小合计 512 MiB 的 ZIP、重新解析并删除。没有原始文件的文档会从 ZIP 中跳过。把文档移入另一个知识库需要管理员。疑似卡住对当前页的文档 id 读取 stall_state，并只过滤这一页。正在解析或收尾的一行显示当前阶段，以及其中已经结束的阶段所占比例。队列中等待的卡住状态显示为排队中。活动中的列表行和上传任务共享持续的批量读取，同步解析状态、错误、待完成子任务和滞留状态，也包括不在当前筛选或文件夹里的上传任务。解析结束时刷新列表，离开知识库后丢弃晚到的响应。

• 查看打开文档页，可切换「内容与分块」「处理流水线」「自定义元数据」。宽阅读页左侧是原文，右侧是摘要和分块。页头显示面包屑、文件类型、解析状态、大小、文件夹、分块总数、更新时间和标签。加载期间标题和摘要使用骨架。原文使用「预览 · 类型」标签：图片和 PDF 使用原文件字节，Markdown 使用共享渲染器，Word 保留段落，PowerPoint 按幻灯片显示独立编号卡片，Excel 保留工作表名和单元格位置。图片描述和 OCR 与文本分块一起读取。资源图片经所在知识库加载，移除时释放对象 URL。分块卡显示从 v1 开始的版本、字数、编辑、历史和召回启用开关，开关两种状态在两种主题中都可辨认。分块启用、正文保存、索引重试和回滚共用每个分块的提交锁，直到请求结束。分块和元数据保存拒绝重复提交，并保留保存期间的新输入。启用状态写入失败时，保留已存状态和草稿，可以重试。冲突刷新已保存修订号并保留编辑；「基于最新版本重试」提交保留的编辑。索引失败保留编辑器并提供重试。历史对比各保存版本与当前正文，回滚先确认，回滚后保留中间版本。修订显示代理返回的成员名，或「系统」「数据源」「来源未知」；不显示上游 UUID。旧响应仍可使用匹配的当前空间成员名。摘要重新生成保持生成中状态，直到读回完成后的摘要。处理轨迹统一使用秒，父阶段包含子阶段；失败和卡住卡片位于瀑布前，停止解析需要确认。元数据最多 20 项，保留字符串、数字、布尔和空值类型，用于总结和召回后的文档上下文，不影响索引或召回排序。生成的问题可以新增、重新生成，或确认后删除。分块编辑后，问题区内的小提示将已有问题标记为可能过期。短暂操作结果使用成功、警告或错误 Toast；切换页签清除 Toast，保留编辑和对应冲突状态。引用操作向对话草稿插入引用；「在对话旁打开」进入知识 dock。这些写入不刷新知识库列表。

• Wiki 页签以树形或按类型的列表展示文件夹和页面。无搜索词时，文件夹计数使用服务端子树页数。新建、删除和移动页面后，重读受影响的文件夹及其已知祖先目录，不预取后代目录；删除文件夹后重读其父目录和祖先目录。有搜索词时，只计入已加载且匹配的页面。每一级同时请求页面类型 summary,entity,concept,index,synthesis,comparison 和不带页面类型的同一级列表。带类型的请求保留空文件夹，不带类型的请求保留只含其他类型页面的文件夹。打开页签时还会读取每个根文件夹里的页面，因此页面移动后，按类型的列表和标题搜索仍能找到它。它按标题、摘要和别名搜索，并把页面拖到文件夹上、确认后移动。它通过 WikiPageReader 阅读页面。阅读页显示本地化的类型名、编辑来源、带 [[slug|label]] 链接的 Markdown，以及别名、被链接、来源文档和链接到。空的页面类型在阅读页和列表分组中显示为「手工页面」。新建使用包含标题、slug、类型和可选 Markdown 正文的对话框；创建失败时保留填写的字段。六种生成页类型对应 WeKnora 的 page_type，选择「手工页面」时不发送类型。编辑器在标题、别名、Markdown 正文和编辑说明的带标签字段上方显示页名、编辑中标记和基准版本；取消与保存位于右下角同一行。别名每行一个，编辑说明独立于页面摘要。提交期间可以继续输入；响应后保留新增草稿并采用返回的基准版本，同时阻止重复提交。保存完成不会重新打开已经离开的页面。成功使用浮动 Toast，切换视图或四秒后清除。它可以新建、编辑和删除。版本卡片分行显示版本、来源、成员与时间，接口提供的编辑说明单独显示。有正文的快照对比标题、可用的别名和完整正文，改动行带底色，确认后才执行回滚，取消不发送回滚请求。缺失的快照会说明原因，且不能回滚。删除在对话框中确认。版本冲突是 KNOWLEDGE_CONFLICT；提示读取实际最新版而不替换草稿，并提供「加载最新版本」与「覆盖保存」。最新版读取失败时不显示推测版本；加载成功后才放弃提交时的草稿并清空旧编辑说明；覆盖先读取最新版本，再按该版本提交保留的草稿。待处理单页问题显示在阅读区顶部；全库与单页列表在抽屉中显示类型、报告来源和接口提供的时间；忽略后移出列表。问题可以忽略，或将知识库 id、问题 id、slug、说明和疑似文档 id 传给对话回调。应用把这些信息追加到当前 Session 的草稿，不提交消息，也不调用自动修复。对话挂载时，仅当原账号与空间仍为当前值才追加这些信息；知识库 UI 卸载时取消等待中的交接。页头在类型和来源芯片上方集中显示引用、编辑、历史、图谱跳转和删除操作。摘要链接复用正文链接渲染。右栏优先从已加载的同库页面解析标题，用图谱节点补齐缺失标题，从同库文档列表解析来源文档名；缺少名称时显示可读提示。来源文档打开现有阅读页，引用向对话草稿插入 Wiki 引用。编辑者复用当前空间的成员解析，未匹配的 id 隐藏。历史替换阅读页，提供返回页面入口，删除和新增行分别使用红绿底色及减号和加号。目录上方的通栏状态显示接口提供的队列、页面和问题数量，并从已加载文档列表显示处理中文档名。队列非空时即使没有解析中的文档也显示「索引中」。目录常驻操作使用带标签的图标按钮，页面节点显示类型色点。链接图只在图谱页签显示，画布底部常驻类型图例。这些写入不刷新知识库列表。根目录新建在请求结束前保持弹窗并锁住提交与关闭；失败时保留输入名称。图谱节点、类型筛选、图例和目录色点共用页面类型颜色，对比类型在两种主题下都保持冻结稿紫色。

• 检索条数显示 Top 3、Top 5 和 Top 10。检索结果用带名次的卡片显示来源芯片、相关度条和定位分块入口。片段去掉 Markdown 标记、图片链接和表格分隔符，同时保留查询高亮。阈值与重排沿用服务端设置。图片筛选无匹配时保留数量并提供清除筛选入口。检索测试以混合、向量或关键词发送一个问题，并在文档页定位到命中的分块；Wiki 命中打开 Wiki 页签。活动记录供管理员或个人空间本人查看，说明保留策略，通过操作与结果菜单筛选；筛选空态与筛选栏都提供「清除筛选」。分页显示「加载更多」、「加载中」或「没有更早的记录了」。发起人优先显示公共成员名称，系统、数据源与未知来源使用本地化标签。对象名称使用记录标题或同库 Wiki slug。详情列出接口提供的全部 JSON 前后值，脱敏值显示服务端的隐藏标记。成员看不到该页签，若该页签已经打开则看到只读说明。图片画廊通过 GET …/files?file_path= 读取字节，用来代替预签名链接。图片页显示包含零值的数量，并说明文档解析后图片会出现；回车或输入框内的搜索图标提交检索。 带边框的卡片将描述限制为两行，并显示来源文档。文档筛选与检索条数筛选使用共享菜单选择器。图片查看器使用共享对话框，包含居中大图、左右切换、序号和固定详情栏；Esc 恢复焦点，方向键切换图片。仅在来源两个序号都已提供时显示位置。OCR 使用共用 Markdown 渲染器。查看器显示上游图片属性，缺值保持缺失。图片列表同时提供 chunkNumber 与 imageNumber 时显示一基的来源位置，不从不透明 id 推断。这些读取不刷新知识库列表。活动读取在结果筛选或知识库变化后丢弃晚到响应，阻止重叠分页，读取失败时保留已有列表和游标。

• 数据源页签列出每个数据源的类型图标、状态、同步频率、上次同步和最近结果。RSS 行在名称下显示类型和订阅地址，管理员可以在行上立即同步。管理员或个人空间本人通过向导添加或编辑（选择类型、配置凭证、选择范围、同步策略与删除保护）。频率步骤标出同步频率、同步模式和冲突策略，删除保护正文在对话框内换行。每条同步记录用独立圆角边框卡片分组显示结果、本地时间、计数与失败详情。同步历史在右侧打开，时间是本地的月-日 时:分，汇总项保持间距并加重数字，每条记录的计数项之间有分隔；部分成功列出失败文档和原因。同步进行时列表保留，该行显示同步中，并继续读取列表直到同步结束。刷新失败时保留已有行，并在表格上方说明原因。创建被拒绝时停在凭证步，按错误类别显示本地化说明，不记下数据源 id。成员看到列表和同步历史，以及带警告图标的不能修改原因。新建 RSS 的连接测试在凭证请求里包含订阅地址，因为该接口没有 settings 字段；创建时地址仍存入 settings。新建时可选请求头留空不发送；返回已创建的暂停源后清空请求头，会用空值替换旧请求头。删除保留已同步的知识。确认框使用已报告的 retainedKnowledgeCount，包括零；null 或未提供篇数时只显示保留说明，不显示数字。同步处理量不能作为该篇数。删除成功后显示成功 Toast 并重读列表；删除被拒绝时显示本地化失败 Toast，保留数据源行。凭证只在填写时转发，不持久化到客户端存储；返回凭证步修改后，向导先更新暂停源再读取资源；编辑时在凭证字段旁说明留空不修改。写入期间冻结控件，服务端字段错误显示在对应输入旁。凭证替换失败时保留当前步骤；过期资源响应不能改变后续步骤，向导卸载后不再启动后续写入。删除标题包含数据源名称，保留知识的说明单独显示。这些读取和写入不刷新知识库列表。

• 问答页签列出、新建并编辑条目，支持导入导出和匹配测试。新建条目在打开「推荐」之前不推荐。列表行的复选框不显示问题文字。条目有相似问或反例时，行内显示它们。匹配测试对话框在对话框内显示每条命中、分数、命中问题和答案；服务端没有命中时显示空结果，调用失败时显示失败说明。导入接受 JSON、CSV/TSV 和 Excel（.xlsx/.xls）文件；Excel 文件只读取第一个工作表。FAQ_IMPORT_MAX_FILE_SIZE（10 MB）和 FAQ_IMPORT_MAX_ROWS（5,000）守护上传；超出任一限制时显示 locale 错误而不进行解析。Excel 解析使用 read-excel-file；模板生成使用 write-excel-file。结果区显示导入数据、新增、合并更新、失败和跳过，进度列出失败行时显示原因，有失败行时提供「修正后重试失败记录」。组织成员可以新建、编辑、删除、导入、导出、修改启用状态和运行匹配测试。按 G2，只有知识库设置、删除知识库和管理数据源需要管理员权限；FAQ 请求被服务端以 403 拒绝时显示本地化权限说明。FAQ 行在圆角列表中显示相对更新时间，已选条目的操作栏浮动在底部中央。列表与两个编辑弹窗共用无标签文案。标签写入使用数字序列 ID；缺少标签信息时提示重试，不发送无效请求。保存请求完成前锁定提交，写入失败保留草稿、标签和选择。问题最多 8,000 个字符，每条答案最多 8,000 个字符，超限就地提示。选择另一个导入文件时立即作废旧预览，当前文件解析成功后才可提交。导入进度有进度条；进度请求失败保留任务 ID，可以重新查询同一任务。失败行使用从 1 开始的行号和本地化安全说明。结果页按每页 100 条读取固定的任务失败接口；下载读取全部分页并使用保存的提交字段，不读取内部对象地址。「下载原因」生成包含失败条目、行号、稳定原因码和本地化说明的 JSON 文件；修正后的失败条目在原任务上以追加模式重试，全部成功后显示完成提示。问答库的列表卡片读取 chunk_count（chunkCount），不必等条目列表。问答库的 knowledge_count 保持为 0。页头在问答列表加载前读取 chunk_count，加载后显示该列表的 total，导入完成后它与 chunk_count 一致。创建、编辑和删除成功后刷新知识库列表；导入结束时在结果对话框关闭前刷新列表。JSON 导出和示例使用 isEnabled（false 为停用，省略默认 true）；导入兼容 is_enabled 和取反的 is_disabled / disabled。CSV 导出的 camelCase 表头与中文、snake_case 表头均可用于 CSV 和 Excel；停用列默认 FALSE。JSON 和 CSV 再导入保留启用状态。FAQ 结果显示 locale 字典的「关键词匹配」或「语义匹配」芯片；匹配方式字段省略时表示 WeKnora 的零值 embedding 匹配，显示「语义匹配」。检索测试对话框在视口内最大宽度为 688px，结果文字可换行，内容区可滚动。

• 设置页签编辑合并后的知识库设置。管理员可以保存、放弃、预览分块并试跑图谱抽取。成员看到同一编辑器的只读形式和原因。模型行显示配置读回的名称，缺少名称时显示可读的默认文字。当前空间的模型目录提供可选的对话/摘要、视觉、Wiki 和向量模型 id；目录不可用时保留已保存选项。名称优先使用 displayName，其次使用提供方名称。Wiki 合成模型沿用摘要模型或与其 id 相同时显示摘要模型名称；独立 Wiki 模型没有名称时显示可读默认文字。保存保留模型 id。设置读回没有视觉 id 时，启用图片理解会在保存前被拒绝。这些写入不刷新知识库列表。实体关系提取需要生成模型、关系类型、示例文本和示例实体及关系。成功的试运行填充草稿实体和关系，保存才写入；放弃更改会一起清除草稿和试运行结果卡；缺失或不一致的示例在发送更新前拒绝保存。加载时显示左侧导航和右侧表单骨架。保存期间冻结输入和放弃操作。较早的辅助请求回调不能覆盖已提交草稿或其他知识库；成功的辅助更新保留无关字段的编辑。详情更新成功而配置更新失败时，页面报告部分保存并重读服务端已提交设置；重读失败时禁止编辑，直到重新加载。服务端字段错误就地显示，并打开对应设置分区；解析规则下标定位文件类型行，索引开关拒绝在策略卡片内显示。所属表单可以向共享编辑器传入可选的名称和描述 fieldErrors，并将被拒绝输入标为无效。保存显示“配置已保存”的成功 Toast，失败 Toast 显示返回的原因；切换分区或四秒后清除。未初始化的零大小配置显示并保存默认分块大小 512 和重叠 80，并标注“默认”；已配置正数大小时保留显式的零重叠。模型控件单行显示，Tooltip 提供完整名称。分块预览使用本地化策略名，编号从 #1 开始。图像设置显示视觉模型、内置观察属性和本地化 OCR 条件。提供方传入 listTags 时，高级设置显示已有候选标签；无法读取目录时明确提示。FAQ 设置说明条目的组成。

• 命中来源、引用与文档页的「在对话旁打开」会切换到已有来源页签，未打开时才新开以来源命名的页签。返回行显示“知识库”。文档页签使用紧凑的只读阅读视图，显示文件类型图标、标题、知识库、绿色完成状态点、作为主按钮的整篇引用与可逐块引用的分块卡片；Wiki 页签显示类型、可匹配的编辑者名称与引用操作。文档分块及紧凑 Wiki 正文和摘要使用文档详情的同一个 GFM 渲染器，resource 图片经来源知识库读取。宽表格在侧栏内横向滚动，图片适应侧栏宽度。正文和摘要的 Wiki 链接从引用页面解析名称，标题不可用时显示本地化提示。「在知识库中打开」返回完整页面。检索页签保持打开，搜索输入框占满侧栏宽度。

• 卡片只在列表报告的 failed_count 大于 0 时显示失败数。缺少该数字时不显示。

• 置顶不是被代理的操作。src/client 按用户和空间把置顶存在本地。

• 列表省略 failed_count 时 failedCount 为 null，卡片不显示该数。应答里大于 0 的失败数会显示在卡片上。

• 文档列表不含 stall_state。readDocuments 对当前页的文档 id 调用 GET …/documents/batch，并从该应答填写 stallState。

• 空文件夹只存在于文档页，直到有文档被移入。仍有文档的文件夹拒绝删除，页面要求先把这些文档移走或删除。

• 「最近使用」分组是 src/client 持有的 Client 本地状态，因为 WeKnora 不报告最近打开时间。

• 分块对比使用修订快照，阶段耗时来自每个 span。没有单独的差异、耗时或问题过期路由。版本冲突是 KNOWLEDGE_CONFLICT。保存分块会重建索引，索引失败时保留这次编辑。不代理删除分块。

• Wiki 文件夹列表在调用方设置时转发 page_types。多于一个 page_types 值时包含空文件夹，并省略其页面都不在这组类型里的文件夹。省略 page_types 时包含含有任意页面的文件夹，并省略空文件夹。Wiki 历史是 GET …/wiki/revisions/{slug}：{ revisions, total, current_version }，每一行省略正文。?version= 返回该修订对象本身，并带上 content；未保留的快照是 NOT_FOUND。省略 content 时 hasBody 为假。没有单独的差异路由。生成状态是 GET …/wiki/stats 的 pending_tasks 和 is_active。省略的 total_pages、pending_tasks 和 pending_issues 在 Client 视图的 reportedCounts 中保持缺失；明确返回的零值保留。不代理自动修复。版本冲突是 KNOWLEDGE_CONFLICT。Wiki 写入不刷新知识库列表。

• 检索测试发送 disable_keywords_match 或 disable_vector_match，不会同时关闭两者。图片字节走 GET …/bases/{id}/files?file_path=，用来代替预签名链接。活动记录只有管理员或个人空间本人可以读，成员得到 KNOWLEDGE_MANAGE_REQUIRED。检索、图片、画廊配置、文件和活动读取不刷新知识库列表。混合检索命中的 match_type 可以是 WeKnora 的数字（0 是 embedding），并记成对应的标签。问答条目的问题列表可以是 null。问答库的条目数在 chunk_count，knowledge_count 保持为 0。响应里没有 faq_count 或 entry_count。新建条目在开关关闭时若应答仍是推荐，客户端再用字段更新把它清掉。问答导入进度读取 added_count、merged_count、skipped_count 和 failed_count（旧字段名是 blocked 和 blocked_entries）。success_entries[].index 是提交数组中的位置，seq_id 是条目 id。缺省的计数是 0。不读取 failed_entries_url。任务结束后，通过字段更新接口给成功的行恢复文件中的启用和推荐状态；已部署的导入可能重置这些状态。提交的行保存在本 Host 实例中，字段更新成功后清除；Host 重启会丢失它们。FAQ 检索透出数字或字符串 match_type。WeKnora 的 FAQEntry.MatchType 使用 json:"match_type,omitempty"，所以省略的值是零值 embedding 类型，显示「语义匹配」。这个默认值仅用于 FAQ 匹配结果。数据源列表是裸数组或 { success, data }，包含字符串设置和最近一次同步记录。创建和更新应答是数据源对象或 { success, data }。同步记录用同样的列表形式。进行中的记录 result 为 null；结束后的记录带计数，并可能带 errors，空的 message 用 code 补上。凭证值不会回显。管理数据源需要管理员；成员可以列出数据源并读取同步记录。数据源的读取和写入不刷新知识库列表。

• wiki_read_issues、wiki_update_issue、wiki_index、add_document、update_document、delete_document 的应答没有本包已知的 WeKnora display type；这些卡片显示查询和有界摘要，不带命中。

开发备注

无。