知识库改造：所有者定下的方向（2026-10-23）

这是所有者 10-23 下午给出的知识库方向，作为知识库改造各任务的依据。设计权威仍是通用模型：docs/design/generic-model.md、contracts/model.json，用 node tools/show-element.ts K01 K02 K03 K04 K05 B01 B02 B03 查元素；知识包的实现见 hub/knowledge/README.md。照这里办，不另造概念或词表。

前提：Hub 不调用任何模型，Hub 与 Circle 联动，统一处理平台接入的结构化与非结构化资料。

一、资料分两类（修订：所有者 10-24）

修订：所有者 10-24。原先按机器结构、作者结构、自由文本三类整批解析；现在只有 adoc 手册（APP、CLI）和命令树 XML 由 Hub 的生产器生成，合成初始树苗（docs/hub-r4-tasks/kb-seedling.md）。其余资料——构建头、测试清单（用例）、缺陷导出、规格、工单纪要等自由文本——一律”Circle 用到了才放进 Hub”：实际工作里读到、引用到的原件和由此得到的结论，才经回注运行（带逐字引文、Hub 核验）进入 Hub 知识库，挂到树苗上或作为树苗外的独立对象；不再由生产器整批解析。

  1. 生产器生成：adoc 手册（APP、CLI）和命令树 XML。由 Hub 的生产器机械解析，合成每条产品线 × 版本线一棵的初始树苗。
    • adoc 产出：章节路径、命令签名锚、取值域、示例。示例只作参考，不参与判定。
    • 同样的输入给出同样的字节。
  2. Circle 用到才进：其余一切资料（构建头、测试清单、缺陷导出、规格、工单纪要等自由文本）。由 Circle 在实际工作里读到、引用到时带出处喂进来，不进树苗，进挂在树苗旁的喂入层（不进根摘要），带版本绑定（已绑定 / 未声明 / 冲突；定不出版本的进产品线不分版本范围、标”版本未声明”，照常参与，单列计数）；回归范围、巡检、追溯能看到多全，取决于 Circle 喂进来的有多全。三条硬要求的落法（必须回 = 凡经 Hub 读的都在；按格式 = 来源 schema 由 Hub 程序填、自由文本按结构契约；结构先定 = 树苗布局写死在 docs/hub-r4-tasks/kb-seedling.md + 生成的 knowledge-structure@1）见 docs/hub-r4-tasks/kb-feeding.md。运行中不问人，待办只登记在控制台；冲突两说并存标记，伪造按顺藤摸瓜式核验整份拒收。

二、Circle 和 Jev 的产出放在哪

  • 按文档的产出存到 Hub 的候选层：分类、归位提议、声明、关系。
  • 按任务的产出只进运行记录：排序、取舍、分数。
  • 层级和依据等级由来源决定（词表 provenance_type、basis_rank），模型的自信不改变等级。
  • 归位提议由 Hub 按确定性规则核验：引文逐字出自源文件、路径可解析、不越过声明。这条通道已由独立回注运行实现（决定 25）。

三、树（K01）

  • 每个产品线@构建一个内容寻址的根。未变子树共享，版本差就是回归范围。
  • 条目是原文片段，加上生产器声明的种类和适用条件（型号、平台、起止构建）；抽不出的记“未声明”。硬件平台是条目的适用条件，不是树的一个轴。
  • 落点是结构规则：
    • 字面能定的直接挂。
    • 跨叶主张挂最近公共祖先，不造合成路径。
    • 无锚散文（APP 手册约四成）按源自身的章节层级挂到章节节点，再按命令字面做交叉链接，不能留在根下未归位。
  • 没有产品线的源文件照样存、照样能引用，但不挂树。

四、三层写入（K03）

  • 树只由生产器写。
  • 观察层：Hub 在核实运行中采到的回显，只追加。
  • 候选层：按决定 25 与决定 35（知识库第 6 项），候选留在 Circle 本地，Hub 不存私有候选，也不提供写本人候选层的入口。
  • 观察层和候选层不计入根摘要，重建只动树本身。

五、Hub 不裁决矛盾

  • 矛盾主张只按 B01 R[2] 作为可机器检查的反驳条件打标：两条都返回，带来源和时间。
  • 矛盾靠自动化测试和沉淀步骤（P10）逐渐消融。Circle 侧的整合技能已有（jev，随 knowledge-contribution 包下发）；是否定时运行仍未定。
  • “实际怎样”与“应该怎样”冲突时，不自动判谁胜。产物是缺陷候选或漂移记录，由用途决定。

六、环境信息和通用知识

  • 环境信息（床位、主机、IP）是 D 的资源记录，不进知识树。
  • 通用知识拆成三种：
    • 包规则：随包的版本。
    • 外部规范：独立对象，从节点链接。
    • 产品线根上的全版本事实：要负责人署名。
  • 版本别名表（一个产品多个名称，FAMX 即 FAMY）的修改要留修订记录，并且可以回滚。

七、从 SyntheticReference 只取精髓，不搬形态

  • 取：“语义判断归模型，结构操作和存在性核查归代码”的契约（SyntheticReference docs/footprint.md）；手册转换链的身份耦合、同批换代、fail-closed 纪律（SyntheticReference docs/HANDOFF_manual_catalog_2.90.md）。
  • 不搬：不按版本复制节点目录；不 rebuild 加搬运；不用收据钉和双生常量；不用向量库；不用五层认知序。
  • SyntheticReference 位于 ../synthetic-reference-engine，只读参考，禁止运行、导入或复制其代码、配置、凭据和业务数据。
  • 新代码一律 TypeScript；生产器在沙箱内运行，没有网络。

八、待调研的四项（各自独立）

  1. asciidoctor.js 能否在生产器沙箱内运行，并直接给出章节路径、签名块和表格。
  2. 用 APP 手册的真实章节验证“章节路径与命令路径共存一棵树”的落点规则。
  3. 在真实手册里找同一版本下按平台分叉的内容，验证适用条件的三个字段够不够用。
  4. 统计现有知识库源文件中，手册、命令树、用例文档、发布说明之外的自由文本占比，决定派生数据机制是否推迟。

工作在各自的 worktree 分支上进行，不推送、不建 PR，提交只加显式路径并带 -s 签名。

集成者 10-23 核对到的事实

  • 手册库里只有转换后的 md 和 SyntheticReference 生成的 catalog.json，没有 adoc 原件；catalog 的 identity 里记着各章 adoc 的 sha256 和行号。要直接接 adoc，先要所有者给出 adoc 的来源。
  • 现在的手册生产器读 md 和 catalog.json，只把命令锚挂到 /commands/...，其余段落留在根下未归位。
  • 候选层和观察层的记录形状已经有了（hub/knowledge/layers.ts），但运行里的提交还没有写候选层的通道，K04 R[6] 的归位提议核验也没有。（2026-10-24 更新：核验已由 knowledge-contribution 包的独立回注运行实现；写候选层的入口按决定 25 不提供。）
  • 版本别名在产品包的 names 里，随包的版本发布，修改天然留版本、可以下架回滚。是否还要单独的别名修订记录，在任务里核对。
  • 所有者 10-23 告知：adoc 原件在手册库所在的那台服务器上。集成者只读核对：
    • 手册库的 WebDAV 只暴露发布目录（cli、app、spec、qa、product、release），没有 adoc 的输入目录；
    • 这台 Mac 上没有那台服务器的 SSH 配置。

    所以要读 adoc 原件，还要所有者给出读法：在 WebDAV 上只读暴露 adoc 输入目录，或者给只读的 SSH。

现在的 md 是怎么生成的（读 SyntheticReference 的说明和脚本得到的事实，没有运行或复制）

SyntheticReference 的 docs/HANDOFF_manual_catalog_2.90.md 和 scripts/maintenance/adoc2md.py 描述了服务器上的转换链：

  1. 输入一个目录，递归找出所有 adoc，按所在目录分组（例如 cli_cn）。
  2. 同组的各章按文件名里的数字排序后合并。
  3. 合并稿经 asciidoctor 转成 DocBook 5，再经 pandoc 转成 GFM，得到 <组名>.md。
  4. 各章再单独经 asciidoctor 转成 DocBook，从里面抽出命令目录，写成同目录的 <组名>.catalog.json：签名、取值域、示例（只作参考）。另写一份对账报告。
  5. catalog 的身份记录：各章 adoc 的 sha256，加本轮 md 的 sha256。没有时间戳，同样的输入产出相同的字节。
  6. fail-closed：签名锚定不到、覆盖不全，就算这一组转换失败；下游发现 catalog 缺失、身份对不上（md 被单独改过），就拒收这一版、保留旧的。
  7. APP 手册的复杂多行表格被 pandoc 写成 md 里的原始 HTML，签名因此有两种写法（GFM 粗体和 HTML 里的 strong）。
  8. 有的章节源文件里混有 NUL 字节，一路带进 md。

对 Hub 的 adoc 生产器（计划 K4）的含义：

  • 直接读各章 adoc，章节层级、表格、签名块都能从 adoc 结构里拿到，不必经过 DocBook 和 pandoc 两次转换，也就没有原始 HTML 表格这类转换伪影。
  • 身份耦合、同批换代、fail-closed 这三条纪律照搬为 Hub 的规则：生产器记下每章 adoc 的摘要，组成记录里能查到；一组里缺章或者解析失败，就是这组生产失败，保留旧根。
  • 章节的合并次序（按文件名里的数字）是转换链的约定，要照样遵守，或者由文件里的 include 决定。
  • NUL 字节这类源数据问题照实报，不在生产器里悄悄清掉。