ZhoMind 的设计：从知识准入到可信的工程建议

先读领域，再读决策的演进

CONTEXT.md 定义的核心对象不是“文档和聊天”，而是 Engineering Decision Entry、Query Condition Set、Answer Evidence Set 和 Delivery Acceptance Record：条目回答一个工程抉择，条件限定本次问题，证据支持本次回答，验收记录限定对外承诺。它们不能因为都包含文字和版本，就共用一份可变记录。

本篇沿问题之间的关系解释全部设计记录，而不是把功能清单扩写一遍。来源包含本地工作区 CONTEXT.md、29 份工作区设计 ADR，以及公开实现仓库的 5 份 ADR；中英文镜像不重复计数。工作区存在两份编号为 0010 的历史决定，下文分别解释。为避免编号冲突，标题区分“设计 ADR”与“实现 ADR”。¹

这些文档不是同一时刻写成的。早期面试作品与小型文档问答的限制，部分已被团队 Pilot 的领域定义和实现 ADR 收紧或扩展。明确写了取代关系的按新决策解释；没有正式取代声明却存在差异的，保留差异，不替仓库补造一条决策历史。实际运行机制见技术页。

一、先决定为谁整理什么知识

设计 ADR-0017：围绕工程决定，而不是框架目录

按厂商文档章节建库容易获得大量内容，却不能直接回答跨框架的生产取舍。因此知识以工程问题为单位：说明适用条件、推荐默认、替代方案、失败模式和验证方法；框架 API 只是带版本的实现映射。中文解释保留英文标识，避免翻译掉用户真正需要检索的名称。

代价是编辑必须综合证据，不能靠批量搬运完成覆盖；收益是读者能比较方案，而不是只找到某一页文档。早期 ADR 聚焦 Agent、设想固定规模首版和统一复核期限；当前领域已扩展到生产 RAG 与 Agent 工程，以实际覆盖和可持续维护决定规模，以风险和来源变化触发复核。这些早期数量、期限不应重新包装成永久门槛。²

设计 ADR-0027：先建立证据，再写顺畅的正文

如果先让模型写出一篇流畅文章，再补几条链接，草稿很容易成为自己的依据。该决策把顺序倒过来：定义问题、收集来源、列主张、记录版本和冲突，最后才写建议、示例与验收问题。

这增加前置研究成本，却允许审校者逐项质疑结论。早期要求固定数量的一手来源；当前 CONTEXT.md 更强调来源的允许用途与条目保证等级。来源数量不能自动证明支持充分，AI 辅助起草也不等于独立审校。²

设计 ADR-0028：书目必须落到具体主张

一篇文章末尾有来源，不代表其中每个数字、版本行为或安全建议都得到支持。因此重要主张要明确关联证据，让读者知道哪一条来源支持哪一段结论，而不是让整份书目替整篇文章背书。

逐项标注需要维护，收益是修改一项结论时能找到受影响依据。当前领域进一步区分 Source-Grounded、Claim-Linked 与 Release-Assured：普通已审校知识、高影响主张和命名高保证版本承担不同义务，不把最严格合同无差别施加给每次内部更新。²

设计 ADR-0020：可编辑正文与可校验元数据分开

条目采用 Markdown 正文和结构化 front matter。正文解释理由与取舍，元数据保存稳定身份、审校状态、来源、适用版本和复核日期。若把这些信息藏在文件名或自然语言里，引用、准入与时效检查就只能猜。

Schema 与迁移成为新增成本，换来人能编辑、程序能校验的共同格式。标题可以润色，权限和来源状态却不能靠改一句文案发生变化。²

设计 ADR-0026：改标题不改身份，换问题才换条目

知识会重命名、补充和修订，历史引用与反馈不能随之断裂。不可变 entry_id 因而跨标题、发布版本、验收和反馈保留；实质上换了一个决定，则创建新条目，并明确旧条目的取代或撤回。

相比拿文件名作身份，这需要多维护一层关联，却避免“链接还在，背后问题已换掉”。它也是后面冻结证据和版本清单的前提。²

二、编辑权威不能由运行副本代替

设计 ADR-0019：公开源码、私有编辑与部署副本分层

公开代码需要可检查，真实知识和完整验收材料却未必可以公开。设计因此把内容权威放在受控编辑仓库，公开仓库保留 Schema、模板和合成示例，部署数据库只承担发布副本。

这增加发布协调，却避免一次 Git 推送意外公开语料，也避免服务器里的最新一行数据反过来决定“当初审校过什么”。版本控制只是可选物理载体，核心要求是权威可保留、可审计、可重建。²

实现 ADR-0002：用不可变记录和追加事件证明审校

分层原则落地后，还必须回答：谁批准、批准哪次修订、来源现在是否可用？实现选择不可变条目、修订和来源记录，加上追加的角色接受、审校与来源事件。作者不能独立批准自己的实质修改；维护者要接受责任；系统管理员也不自动获得私有编辑权限。

这比在文档行上放一个 approved 布尔值复杂，但能够重建批准依据。来源未知默认不可用，运行副本不能自封为权威。导出、Bundle 和 Candidate 又分别绑定内容身份：导出不触发发布，导入只安排工作，管理员显式派发才允许执行。³

候选构建的恢复也遵循同样选择。Worker 必须持有当前尝试的租约，索引完成后再次核验权威；失去租约不能抢写成功或清理不属于自己的数据。资格写入与最终提交共享约束，避免来源恰在检查后失效仍生成合格候选。代价是更多事件、锁和清理义务，收益是重启不增加发布权。

设计 ADR-0003：构建成功只产生候选

材料解析和切分成功，只能说明机器处理完成，不能证明适合让团队引用。因此管理员先检查 Candidate，再显式发布；替换构建期间保留旧发布版本，新版本发布后才切换未来检索资格。

多一次检查牺牲自动化速度，却避免坏切分立即影响回答。逻辑文档身份与具体代次分开，也让“替换”不等于两份相互矛盾的知识长期同时生效。候选发布迁移的具体集成进度仍由迭代记录说明。⁴

设计 ADR-0009：先控制更新入口，再扩展接入方式

首版选择管理员手动上传、构建、检查和发布，明确限制格式、大小，并排除自动外部同步。理由不是外部同步没有价值，而是初期不能让外部内容变化绕过内部审查。

代价是更新工作较重。当前领域已允许经审校的 Git、批次或连接器材料进入同一流程；保留下来的是 Candidate 和显式发布边界，不是“永久只准手动上传”的入口限制。⁴

设计 ADR-0005：撤回来源，但不伪造历史

删除来源后继续展示原摘录，会让用户误以为它仍是有效依据；直接抹掉整段历史，又无法解释过去发生了什么。因此未来检索立即排除撤回版本，历史保留引用身份与不可打开的撤回提示。

这要求维护历史投影，而不是只删除索引。代价换来两件事同时成立：知道过去依赖什么，又不把被移除的材料继续当作当前证据。该行为不是所有日志、备份和终端副本的物理擦除保证。⁴

三、团队准入与知识可信度分别治理

设计 ADR-0006：一个共享范围，暂不伪装文档级权限

早期产品让所有获准成员读取同一个已发布知识库，而不混入个人或受限文档。这放弃细粒度知识空间，降低权限与检索组合复杂度；代价是不能把它当作任意敏感资料的存储库。

后续来源元数据可以声明访问范围，但声明本身不能证明任意 ACL 已实现。只有当前授权边界实际支持的资料才能进入回答，不能把“有 scope 字段”写成“已支持所有私密文档”。⁵

设计 ADR-0004：有期限的邀请取代开放注册

小团队不需要公开增长入口，却需要明确谁获准进入。早期选择管理员手动发送有期限、可撤销的重复使用邀请码，不接邮件平台，注册者不能自选管理员角色。

这样减少接入依赖，但依赖管理员分发和撤销。它是历史方案：后来的实现 ADR-0001 改为一次性原子消费，不能同时把“可重复使用”和“一次性”描述成现行行为。⁵

设计 ADR-0007：管理员来自初始化和明确提升

管理员掌握发布和成员控制，如果允许公开注册页面凭共享秘密创建管理员，初始信任就散落在公开入口。设计改为部署时初始化首位管理员，之后由已有管理员提升成员。

初始化和继任必须有人负责，这是成本；收益是管理权的来源明确，不从普通邀请或客户端角色字段中推导。⁵

设计 ADR-0008：先撤访问权，再按保留规则处理记录

成员退出时立即吊销会话、禁止后续访问，但不把停用等同于立刻删除账户和全部历史。这样能够保留身份关联与必要的恢复信息，代价是账户生命周期与内容保留需要分别管理。

“不立即删除”也不是无限保存对话。成员私有记录仍受自己的删除和到期规则约束，停用不能成为永久保留内容的借口。⁵

实现 ADR-0001：权限查当前服务端事实

浏览器缓存和 JWT 中的旧角色可能在成员被停用后仍存在。因此受保护入口查询当前服务端成员状态；邀请码以条件写入一次性消费，Bootstrap 由数据库约束为唯一，不能靠重试重建管理员或改密码。

审计只保存必要身份和摘要，跨数据库与会话存储的失败也要留下可续办事件。这增加迁移与失败处理成本，但使竞争注册、停用和会话清理可解释。旧邀请无法证明未使用时会保守处理，管理员需要重新签发。工作区词汇表仍保留重复邀请措辞，此处明确按更新的实现 ADR 描述，差异不被隐藏。⁶

四、回答之前，先决定什么算充分证据

设计 ADR-0021：分块保护决定的条件

固定字符窗口可能把“适用于什么情况”与建议拆开，留下看起来肯定却失去前提的片段。因此工程条目采用结构感知分块：元数据单独解析，尽可能保留分节，超长内容沿句子边界拆分并保留条目与章节身份。

这增加解析与测试成本，但保护了条件、替代方案和来源关系。研究用旧分块策略另行保留，避免一次产品优化同时改写旧实验的比较对象。²

设计 ADR-0002：宁可明确不足，也不无据补全

首版要求知识回答带可打开的发布来源；没有有效摘录就不生成，窄范围小聊才有明确例外。这是对覆盖率的主动让步：系统不能为了每问必答，用模型常识填补知识空白。

但首版的“非空上下文”仍不足以证明建议完整。当前领域与实现 ADR-0003 已把门槛推进到条件和主张覆盖。可检查引用仍是必要条件，却不再被误当成充分条件。⁷

实现 ADR-0003：确定性充分性取代前三条和非空门

授权检索解决“可以看什么”，排序解决“什么相关”，都没有解决“是否足以支持这次决定”。充分性因此单独检查可见 QCS、适用性、已审校问题覆盖、必要分支、主张链接、冲突与保证等级。

选择的是预算内最小可用证据组合，而非无条件取前三条。缺决定性条件、待复查、证据冲突或必要内容放不进预算，都形成明确不足；不能通过裁短必要证据制造完整性。保守拒绝更多问题是代价，缺口可定位、裁决可重放是收益。⁸

当前实现把数量与字符预算固定在 Pilot 合同中；领域的 Retrieval Policy Profile 则允许未来经评估形成新版本。两者分别是现行实现约束和可演进的策略边界，不用“可配置”暗示运行时已经能任意调整。

设计 ADR-0015：同一次回答只选择一次证据

若 HTTP、SSE 与历史分别挑选来源，用户可能刷新一次就看到不同依据。该决策集中回答执行，冻结一个 Evidence Set 和每项摘录，让生成、引用、持久化和展示使用同一份内容。

适配器失去自行修补答案的自由，却避免多个出口产生多个事实源。选择策略演进后，这条 ADR 继续约束单一执行权威和冻结快照，不再承担旧选择算法的定义。⁷

设计 ADR-0016：来源是数据，不是生成策略

即使一段文字已经发布，其中的“忽略规则”仍然只是待引用内容。策略、问题与证据因此处于结构化分离的 Prompt 区域，凭据、运行配置和私有历史不能因为排查方便被一并发送。

这要求单独的 Prompt 合同与对抗案例，也限制了上下文自由拼接。它不等于模型已经免疫提示注入：确定性边界测试与真实 Provider 的有界对抗观察必须分别报告，攻击夹具不能进入正常发布语料。⁷

五、可用性不能悄悄扩大数据去向

设计 ADR-0010（故障关闭）：服务失败比未批准转发更明确

最初只准一个已批准 Provider 接收问题与证据。它故障时明确返回不可用，不因为另一个端点有凭据就转发团队数据。

这是以可用性换取可预测的数据处理边界。后来允许批准回退，并不否定这一理由：被取代的是永久单路由限制，保留的是没有批准就不能发送。⁹

设计 ADR-0010（单一批准配置）：先验证替换，再影响新请求

另一份同编号 ADR 解决配置更新：密钥受保护保存、不回显；新配置验证成功后才原子替换，进行中的请求继续原配置，失败保留旧值。它避免管理员改设置把正在执行的请求变成混合版本。

代价是配置不能靠随手改一项即时传播。旧文档还限定 Embedding 为服务端配置；当前领域已允许经管理设置选择，但索引仍须匹配有效模型。不能把早期入口限制与长期兼容性要求混为一谈。⁹

实现 ADR-0005：有界恢复只能走显式批准路由

后续把单 Provider 扩展成一条版本化路由：主路由和每条备用路由都独立批准，绑定模型、端点、数据范围和总预算。保存草稿不是激活，激活还需要匹配的接受证据、连接验证与原子指针切换；新请求捕获新版本，旧请求保留原版本。

允许连接、超时或确定性答案契约失败触发有界尝试，却禁止以回退绕过证据不足、取消、权限、隐私和安全拒绝。每次使用相同冻结载荷。额外批准和观测增加成本，换来可恢复但不偷偷扩权的生成路径。¹⁰

这一 ADR 仅部分取代实现 ADR-0004 的失败分类：符合批准路由合同的归一化失败与归一化路由耗尽可以形成 Generation Unavailable。未分类应用错误、输入或观测信封错配仍是应用失败，不能伪装成不足；冻结证据、隐私与传输规则继续有效。Local Development 的替身证据不授权真实 Pilot。

六、保存回答，不建立第二份管理员对话库

实现 ADR-0004：运行状态与回答结果分开

冻结证据还不足以防止某个出口按消息文本猜结果。因此一次获准问题保存独立私有 Answer Execution：请求、QCS 与消息绑定不可变，事件追加；只有完成状态才拥有四种回答 outcome，停止或失败不补造回答。

同一会话可以显式继承条件，但每轮形成新身份，不能从隐藏画像补前提。HTTP、SSE、刷新与历史校验同一结果；流式中断保留交付事实，不把缺失终止标记当成功，也不重新检索来“修好”历史。代价是更严格的错误投影和更多状态，收益是同一个问题在不同出口仍是同一次执行。¹¹

领域允许生成不可用时展示有界证据预览，但该 ADR 的当前公开投影更窄：不显示来源、引用或预览。实现 ADR-0005 没有新增这一预览能力。这里保留“领域允许”与“当前出口提供”的区别。

设计 ADR-0012：私有对话有删除和保留期限

管理员需要运行系统，不需要阅读每个人的问题。对话归成员所有，可自行删除并按保留规则到期清理，管理面没有浏览私聊的权限。

代价是不能拿永久聊天档案做追溯或训练；收益是使用知识库不自动贡献一份管理员可查的个人记录。闭合执行的不可变性也只在保留期间成立，不凌驾于私有记录删除。¹²

设计 ADR-0013：运营事件只回答运行问题

路由、耗时、结果和归一化错误足以解释许多故障，不必把问题、答案和来源摘录全部写入日志。运营事件因此有字段和保留边界，不成为第二份对话副本。

排障信息会少一些，工程上必须设计明确错误分类。作为交换，诊断系统不因“方便查看”取得内容权限，Trace 也不再承担回答的语义权威。¹²

设计 ADR-0022：反馈进入维护，而不是进入私聊审阅

用户可以指出有帮助、证据不足、过期或超范围，并主动补充说明；反馈绑定回答与知识身份，但不把会话一并交给维护者。

当前领域把信号进一步分成内容、时效、覆盖、检索行为和产品问题，分配责任人，独立验证后才形成可长期保留的非个人发现。这样比自动收集对话慢，却避免把一条用户反馈当作已证实根因，更不能直接自动发布知识。²

七、让人发现覆盖，而不是假设系统无所不知

设计 ADR-0025：聊天之外提供只读知识地图

用户不知道库里有什么，就容易把超范围问题当系统失败。知识地图展示已发布条目的领域、标题、审校或版本提示、获准摘要与适用来源线索，帮助形成下一问；早期公开知识版本还展示公开来源数量。候选、未发布内容、私有运营与管理操作继续隐藏。

这增加一个浏览入口，却不把产品扩展成全文档案系统。它与聊天互补：地图说明可用范围，回答说明某个具体问题是否得到支持。²

设计 ADR-0024：命名知识版本要有清单身份

“当前知识库”会变化，不能用它解释某次发布。Knowledge Edition Manifest 因而绑定条目、工件、来源和验收身份；需要恢复旧版本时重新发布对应清单，而不是猜测某天数据库的内容。

清单维护与版本协调是成本，收益是命名版本可以复查。它不同于单次实验的 Evidence Manifest，也不等于账户、对话和运行库的完整备份。¹³

八、评测、交付和运行承诺分开建立

设计 ADR-0001：迁移可用性与检索质量分开比较

Dense 暂不可用时使用另一条检索路径，是维持服务的机制，不能因此叫作“经过验证的混合检索”。独立 Evaluation Retriever 在相同语料与输入上比较 Sparse、Dense 与融合，Migration Retrieval 保留原来的可用性职责。

维护两个边界增加工作，却让对比可解释：不会把缺索引时还能返回结果，误写成融合算法提高了质量。¹⁴

设计 ADR-0018：知识库验收不借研究查询集代考

研究集比较算法，实际知识条目的验收则要覆盖工程问题、改写、条件和边界。复用一小套研究问题容易获得漂亮指标，却不能说明新知识真正可用。

因此知识验收有自己的身份、问题和证据。早期合同要求每条条目先记录 Gold Evidence，先检查覆盖与噪声，再检查代表性认证 /chat 结果、来源身份和可打开摘录，不能等看到答案后反过来挑支持材料。

额外编写和维护验收集是成本。当前保证等级允许普通内部条目做风险相称的验证，命名高保证版本承担更完整冻结集合；不是每周发布一条内容都重演整套研究实验。¹³

设计 ADR-0023：先声明发布门，再观察结果

上传成功、演示成功和一个总分都容易掩盖失败条目。命名版本在看结果前声明范围和门槛；条目可以独立发布，但不能把只完成一部分称为完整 First Edition。

代价是不能事后缩范围或改阈值换一个通过结论。早期 top-three 与覆盖数值属于当时的版本合同，当前 CONTEXT.md 已将保证等级与交付阶段分开：公开证据发布失败未必撤销其他有效内部内容，完整性缺陷则必须阻断真实受影响范围。¹³

设计 ADR-0011：本地持久化不冒充灾备

首版接受本地数据库和对象存储持久化，索引是可重建派生物；它没有同时承诺异机备份或恢复演练。文件名仍提到备份权威数据，正文却明确收窄为本地持久化，因此不能只按文件名写出灾备能力。

这一选择减少首版运维负担，也留下明确风险。当前知识重建目标可以从编辑权威与验证 Bundle 重建最小知识路径，但不自动恢复账户、私聊和运行期事实，仍不是完整灾难恢复。¹²

设计 ADR-0014：容量与延迟绑定具体工作负载

早期单机版本明确用户量、并发、语料和延迟目标，以避免无限服务承诺。设边界会限制使用规模，却让超限时的扩容、归档和性能问题有责任归属。

当前领域用版本化 Pilot Workload Profile 与 Service Objective 表达这些条件，不把早期数字固化为永久上限。目标未达成就调整或暂停相应部署承诺，不能降低证据、权限或引用不变量。旧版性能缺口仍在实验验证保留。

这也解释为什么 Local Development、Editorial Preview、Limited-Team Pilot、Daily-Use Release 与 Public Evidence Release 不能互相改名：代码可运行、有限试用和日常服务承诺，需要不同证据。¹²¹

最终能够达到的效果

这些抉择串起来，形成的是一个可维护的工程决策知识库：人先审校依据，系统控制可用版本，用户明确问题条件，回答在有限证据内综合建议，历史保留原执行事实，反馈推动有责任人的修订。

共同代价是更多审校、身份、版本和验证，也会拒绝一些看似可以回答的问题。共同收益是遇到争议时能够说清楚：哪个条件未满足、哪份依据失效、谁有权修改，以及哪些用户承诺需要重新验收。流畅回答是这条链的呈现，不是它的权威来源。

来源与范围

阅读快照为 2026-09-08 的本地文档；工作区根目录没有可用 Git 修订，因此不虚构根 CONTEXT.md 与历史 ADR 的公开永久链接。下列本地来源按编号和主题定位，未将私有原文或完整验收材料复制到本站。公开实现 ADR 固定在 c1609dd12523e780149ec7ac546a34509f907757。

本文解释设计的理由、代价和文档演进，不是全部决策的实现合规证明。本次未重跑上游测试、真实 Provider 或团队使用验收。具体代码与出口见技术页，交付状态见迭代记录。