知识库调研 2–4 与 adoc 原件：在真实资料上核对落点、适用条件和自由文本占比

2026-10-23，集成者只读调研。真实内容只留在本机草稿目录，这里只有形状和计数。输入：

  • 一个真实产品同一版本线的应用手册和 CLI 手册：先是转换后的 md 和 SyntheticReference 生成的 catalog.json，后来是所有者给的 SVN 只读账号读到的 adoc 原件；
  • 一个构建的命令树；
  • Hub 数据库，只用 SELECT。

SyntheticReference 只读了说明文档，没有运行或复制任何代码。

调研 2：章节路径和命令路径能不能共存一棵树

结论：章节那一半完全可行；两套层级不能合并，要在同一个根下分成两棵子树。

  • 章节落点：应用手册有 702 个标题，最深 5 层，没有跳级。同一父节点下没有重名标题，第一个标题之前没有内容。3,875 个块和 609 段章节正文都能用 markdown@1 的标题选择器定位，所以全部能挂到自己的章节节点，根下不留未归位。现在的生产器只挂了 84 块（2.2%）。
  • 章节和命令是多对多：一节最多提到 35 个命令；被提到的 650 个命令里，有 260 个出现在两节以上。在 /commands 里求最近公共祖先时，多命令章节有 53% 得到 /commands 本身，等于没有落点，没有一个落到具体命令。
  • 无锚内容是多数：
    • 按章节正文算 53–65%；
    • 按字符算，章节级 24–36%，块级 50–61%；
    • 只看散文是 87–97%。

    锚点大多在示例代码和命令表里。所有者说的“约四成”和 SyntheticReference docs/footprint.md 按它自己的切法算的字符占比一致；切法不同，数字就不同。

据此定的落点规则（已转给 K1）：

  1. /commands 只由命令树生产器写。手册签名在本构建的树里能解析时，作为定义挂到已有的命令节点；解析不了的留在章节节点。
  2. 每个手册片段挂到自己的章节节点 /manual/<手册>/<章节路径>，每份手册一棵。不按标题合并不同手册：同名路径的 50 处里只有 5 处正文相同。
  3. 命令表按行拆：
    • 只有一个签名的行，挂到那个命令；
    • 有多个命令的行，公共祖先比 /commands 至少深一层、并且是树里已有的节点，才挂上去，否则留在章节节点。

    求最近公共祖先不跨两棵子树；得到命名空间的根本身就不算落点。

  4. 交叉链接存作者标出的命令字面，读的时候对锁定根的 /commands 做精确匹配（K05 R[2]）。这样手册子树不随构建变，同一版本线的各构建可以共享（K01 R[1]）。
  5. 解析不到的字面列在生产报告里，作为漂移候选，不为它们建节点。
  6. K04 R[6] 的归位提议只用来把片段从章节节点往更细的位置挪。

待所有者确认：无锚片段按“源自身的章节层级”挂（所有者方向第三节），体裁因此出现在命名空间里；这和 K01 R[0]“按说的是谁归档，体裁只是出处属性”并不矛盾，因为无锚内容本来就判断不出说的是谁。调研按所有者的方向做。

调研 3：适用条件的三个字段够不够

结论：不够，但不该扩成一套条件语言。

  • 同一版本的两份手册里有 125 处明确按条件分叉（应用手册 17 处、CLI 手册 108 处），按类别：
    • 型号 8 处；
    • 平台 39 处：虚拟或物理 8 处、硬件变体 9 处、芯片或卡 22 处；
    • 构建 5 处，都是相对说法，没有“从某个构建起”这种范围；
    • 其他 73 处：内存 51 处、许可 10 处、CPU 数 7 处、部署方式 5 处。
  • 能装进三个字段的情况：
    • 只有 9 处（7%）能用原文给出的值装进去；
    • 21 处（17%）只能当作平台标签，表达不了“没有某部件时”，也表达不了组合条件；
    • 90 处（72%）哪个字段都装不下。
  • 条件大多绑在条目以下的粒度：一行表格占 53%，一句话 31%，一个命令条目 8%，整节或整章 7%。
  • 另有 37 个命令条目和一章安装说明只适用于部分硬件，但原文没写条件，按规则记“未声明”。
  • 品牌从不作为条件写出来，它藏在 adoc 属性里（见下文 adoc 一节）。

建议：

  1. 三个字段保持窄：
    • 型号只取明确列出的；
    • 平台只取明确写出的；
    • 手册条目的构建字段留空：哪些构建用这份手册，由按构建的根和组成记录说明（K01 R[5]、R[7]）。
  2. 装不下的条件留在原文里，按 B01 F[4] 作为目标前提显示“未核对”；有设备回显（观察层）时再核。这不加字段，Hub 也不做判断。
  3. 分叉的表格行和句子按分支拆成各自的条目，没有条件的部分留在共用条目里。
  4. 写在章节开头的条件，是否按位置继承给子节，待所有者定；在那之前不继承。
  5. 隐含“只适用部分硬件”的内容记未声明；Circle 判断出的适用条件只进候选层。

调研 4：自由文本占多少

结论：很少，而且不进树；派生数据机制可以推迟。

  • 占比：连接器读过 1,741 份不同的内容，共 223.2 MB。其中工单类（缺陷和需求）13 份，按条数占 0.75%，按字节占 0.38%。把规格和 QA 的检索结果也算进来，是 1.49% 和 0.54%。
  • 没有进树：知识同步没有读这些自由文本，它们都是作为用例评审运行的输入读进来的；没有任何组成记录用到它们；候选层和观察层都是空的。
  • 真正的缺口是结构：当前一个根里有 27,725 条未归位的用例条目。
  • 还没读的规格和 QA：手册库里的规格和 QA 目录有 1,293 份 Markdown（39.7 MB），读进来以后约占字节的 15%。规格类文档的版本基线待所有者定（K01 R[5]）；在那之前存而不挂（K01 R[4]）。

建议：

  • 自由文本照现在的方式处理：存为可引用的源文件，Circle 按任务读，产出只进运行记录。
  • 缺陷记录按字段拆：头部字段由 Hub 生产器机械解析，只有评论和步骤交给 Circle。
  • 读进规格、QA、发布说明或工单来源时重新测一次。

adoc 原件（所有者 10-23 给了 SVN 只读账号）

  • 主文件和 include：每份手册一个主文件，按固定次序 include 各章：先是前言两件，然后是按编号的各章，最后是附录两三件。
    • include 都是同目录的整文件，没有选项，不在条件里，也没有 leveloffset。
    • 每组另有两个文件，主文件没有 include 它们。
  • 属性和条件：主文件定义 88 个属性，其中一部分在条件里。条件指令只有 ifdef 和 ifndef，切换的是品牌和版本（海外版、不同厂商版），不是硬件平台。各章引用属性：应用手册 38 处，CLI 手册 771 处。
  • 现在的 md 链：它不经主文件，而是按文件名里的数字合并各章，只传一个编码属性。所以 md 里留着没解析的属性占位，条件分支都按“未设置”取。调研 3 里品牌只出现在占位里，就是这个原因。
  • 源数据问题：部分章节有 NUL 字节（应用手册 3 个文件、CLI 手册 7 个）；大多数文件是 CRLF 换行。
  • 标题层级（应用手册）：
    • = 1 个，== 42 个，=== 131 个，==== 266 个；
    • ===== 216 个，====== 52 个；
    • 还有一行用了 7 个等号，那不是合法标题。
  • 按修订号读：服务器支持按修订号读（HTTP v2）。每个目录带最后修改的修订号；按这个修订号列目录，各成员的修订号都不超过它；按这个修订号读文件，和直接读最新的得到相同的字节。所以一组手册可以按“目录 + 修订号”成批读，身份可查。

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

  1. 读法：按主文件的 include 次序读，不按文件名数字。整组在同一修订号上读，组成记录写下修订号、每个文件的摘要和属性集。
  2. 条件和属性：生产器收一份声明的属性集。默认为空，也就是和现在的 md 一样“全不设”。属性集进身份；哪个名称族用哪组开关待所有者定。
  3. fail-closed：下面几种情况都算这一组生产失败，保留旧根：
    • include 的文件缺失；
    • include 带了不支持的选项；
    • include 写在条件里；
    • 用了时间类属性。
  4. NUL 字节：照实报。text@1 已经把它去掉并计数，不悄悄清。
  5. 片段引用：用 text@1 的行号选择器指向各章原件，核心不用解析 adoc 就能核对。