# 首版需求 ## 使用场景 一个 DSH 实例可以直接使用本地 SQLite 知识库，也可以作为中央知识库开放远程访问。另一台 DSH 或未来的桌面客户端安装同一个插件后，可以连接中央知识库。首版面向单用户和 NAS/LAN 部署，不提供多租户能力。 ## 回答后提取 每次成功的助手回答完成后，插件在轮次提交前同步判断是否需要回写，并在回答下方持久化显示逐库结果。提取失败不得阻断下一轮对话。 提取器必须在目标范围内检索已有知识，并产生以下一种结果： - `skip`：没有可复用知识或内容已经存在。 - `create`：没有相关主题文档时，产生新的文档候选。 - `update`：明确选择追加新章节或精确替换/删除过时原文，并保留旧版本。 - `conflict`：与已有知识矛盾，等待用户选择。 审核写入模式下，除 `skip` 外的结果进入待审核区。直接写入模式下，服务端先协调已有内容：完全重复跳过、兼容补充合并并保留版本、带精确锚点的修订替换原文、无法重放的重叠修改进入审核。待审核知识不参与自动召回。 知识库服务保存一个全局回写策略：`conservative`（严谨）或 `proactive`（主动）。严谨模式默认宁可漏记，以长期价值和较高置信度为门槛，接受用户明确陈述，以及最终回答中带具体来源的可靠调研、工具、测试、部署和观察结果；来源类型只作为追踪元数据，不能成为模型自行控制的硬开关。主动模式允许提取可靠推断出的可复用内容，但仍排除敏感信息、临时状态和一次性输出。远程客户端必须读取中央服务的同一策略。 主 Agent 不暴露内容写入工具。普通沉淀和用户当前轮明确提出的知识库写入要求，都统一在完整回答结束后由独立提取调用处理。写入状态、工具资格、尝试、拒绝和结果不得伪装成用户消息或进入回答正文，只能由独立 UI 状态展示。写入结果仍由挂载的审核/直写模式以及服务端去重、合并和冲突保护决定。 ## 知识库与挂载 用户可创建多个知识库，每个库保存名称、回写匹配描述、默认标签和提取要求。匹配描述用于判断当前对话的可复用知识是否属于该库；挂载本身不能导致无关内容回写。主题文档和文档变更候选必须属于一个知识库。 项目和会话可挂载多个知识库。会话默认继承项目挂载；对同一库创建会话配置后，会话配置覆盖项目配置，包括显式关闭。每个挂载可设定： - 是否召回。 - 仅召回、审核写入或直接写入。 - 包含与排除标签。 - 附加提取要求。 没有解析出任何挂载时，不进行召回、提取或回写。 ## 知识模型 一个知识单元代表一篇稳定主题文档，而不是一个孤立事实。相关知识以 Markdown 章节或段落聚合在同一文档中；例如同一 GitHub 仓库的地址、License、版本、维护状态、优缺点、风险与结论必须进入同一仓库文档。文档保存标题、正文、类型、标签、范围、状态、置信度、来源会话、来源消息、创建时间、更新时间和版本记录。 提取器必须先检索相关文档：已有主题使用 `update + targetId`，确实没有时才使用 `create`。更新必须声明 `append` 或 `revise`；旧结论仍然正确时才能追加，过时事实必须通过唯一的精确旧文本锚点修订或删除。同一轮对同一知识库、范围和规范化文档标题产生的多个候选，服务端必须合并为一个文档变更。审核通过和直接写入都要再次执行主题归并、重复检测、修订重放与冲突保护，不能因为模型误报 `create` 而生成同名兄弟文档。 生效文档另有 `open / resolved / complete` 状态。`resolved` 表示问题已解决，`complete` 表示资料收集完成；二者仍参与搜索与召回，但内容进入只读封存。直接回写、审核通过、人工编辑以及同主题误报 `create` 都不得修改或绕过封存文档，只有显式重新打开后才允许继续写入。 首版范围： - `global`：所有项目可用。 - `project`：只在指定工作区或项目使用，并在冲突时优先于全局知识。 首版类型： - `preference`：用户偏好。 - `fact`：事实或背景。 - `decision`：决策或约束。 - `procedure`：操作流程。 - `lesson`：经验结论。 技能设定不属于知识类型，后续由独立插件或模块管理。 ## 检索与召回 SQLite 是本地后端的权威数据源。首版提供 FTS5 全文检索，并为可选 embedding provider 保留接口；未配置 embedding 时功能仍可使用。每次模型请求只自动召回有限数量的相关知识，用户和模型还可以显式搜索知识库。 ## 知识文档与笔记关联 笔记工作区与知识库保持独立：笔记正文不进入 FTS、自动召回或回写。知识文档可以通过独立的多对多关系引用一个或多个笔记文档或文件，关系不嵌入 Markdown 正文。笔记移动和改名不得破坏关联；被关联的节点或其上级目录默认不得删除。 管理台必须在知识文档编辑区外展示“关联笔记”列表，支持打开、添加和移除，不再往正文插入引用语法。已归档或已封存的知识文档不得修改关联。 AI 只有在当前直接用户消息明确要求查看或维护笔记时，才能浏览、搜索、读取、创建、修改、移动或删除笔记。知识与笔记均使用会话绑定的签名句柄，AI 不得猜测 ID；笔记正文只能通过显式读取工具按长度分页返回，不参与自动召回。笔记写操作必须跟随当前本地或远程 Provider，远程服务继续强制校验 `write/admin` 权限，被知识文档引用的节点及其上级目录不得由工具删除。 知识文档引用工具保持独立：只有当前直接用户消息明确要求查看或修改引用时才能执行，并必须重新验证当前会话挂载、项目与标签范围、写入模式和文档封存状态。笔记元数据搜索不得隐式读取正文。 ## 本地与远程后端 插件提供统一的 knowledge provider 接口： - `local` 后端读写本机 SQLite 文件。 - `remote` 后端通过 HTTPS 访问中央知识库。 - `local` 后端设置 `exposeApi` 后，同时承担中央知识库服务端角色。 首版不做本地库与远程库的透明双向同步。数据迁移使用显式导入和导出，远程客户端断网时不得写入中央知识库。 ## 权限 中央知识库为每个客户端使用独立令牌。权限至少区分查询、提交候选、直接写入和管理。普通客户端默认只获得查询和提交候选权限。 ## 管理界面 Web 管理界面至少支持： - 查看和筛选生效知识。 - 创建和编辑知识库，设定标签与提取要求。 - 管理当前项目挂载与会话覆盖。 - 审核新增、更新和冲突候选。 - 修改、归档和彻底删除知识。 - 查看来源与版本历史。 - 管理客户端令牌。 - 修改全局严谨/主动回写策略。 管理界面随插件包提供，复用中央知识库认证 API，不引入单独进程。访问令牌只保存于浏览器会话；AI 生成内容必须明确标记为候选，审核确认前不得参与召回。 ## Docker 插件随 DSH 应用运行，不要求单独容器。`DSH_HOME` 必须挂载为持久卷，使 SQLite、profile、插件依赖和配置在容器重建后保留。密钥只通过环境变量或外部 secret 提供。