任务:读时解析手册里的命令字面,给出交叉链接和漂移视图(K1 的后续)

依据:

  • K05 R[2]:按路径路由加精确匹配检索,不用向量库(node tools/show-element.ts K05 K01 K02)。
  • K1 的 README(packs/product/famx/README.md 436–440 行,在 kb-sections 分支上):
    • 条目在 data.command_literals 里存作者标出的命令字面,生产时不解析;
    • 读时对锁定根的 /commands 精确匹配还没做;
    • 漂移候选只出现在生产警告里。
  • 调研 2、3(docs/hub-r4-research/kb-real-sources.md):交叉链接存作者标出的字面,读时精确匹配。
  • 计划里登记的两条后续:漂移记录、读时解析字面。根不可变,漂移就是“这个根里解析不到的字面”,所以做成读时算的视图,不另存记录。

  • 分支和工作树:kb-links,目录 circle-hub-kb-links(从 kb-sections 开出,依赖已装好;合并时排在 K1 后面)
  • 可以改的路径:
    • contracts/src/ 里产品声明和视图的形状(照生成器重新生成,--check 要过);
    • hub/knowledge/**(视图和读取);
    • hub/server/text.ts 里 get_nodes 回答的链接那一段;
    • packs/product/famx/product.json 和 functions/manual.ts 里算漂移警告的那一段,加重签;
    • 对应的测试。

    别的路径不动;评审、回归范围的包在第二步改。

  • 规则:同前(不推送、不建 PR、不发布、不部署;不碰 7420、钥匙串、环境配置文件和任何真实系统;测试只用合成数据,版本线 10.6 以后;git commit -s)。所有者的规矩:
    • 核心是通用的,核心代码里不出现 command、/commands 这类产品的字;
    • 未知只能是过渡状态;
    • 枚举只来自生成的词表;
    • Hub 只核验,不判断。
  • 验证:npx tsc --noEmit;node tools/gen-contracts.ts --check;node --test --test-concurrency=1 对 hub/knowledge/**、hub/server/**、contracts/**、packs/product/**。

第一步

  1. 产品包声明链接:product@1 的知识声明加 links,写明三件事:
    • 从条目 data 的哪个字段取字面;
    • 链到哪个命名空间;
    • 字面怎么变成路径:按空白切成词,一个词一段;规范化只许声明的几种,没有就照原样。

    核心照声明做,不认识的声明整份拒绝。

  2. 读时视图:对锁定的根,按声明把每个条目的字面解析成目标路径。精确匹配到存在的节点算链接,没有的算漂移。视图给出:
    • 正向:某个路径前缀下的条目链到哪些目标路径;
    • 反向:给一个目标路径,哪些条目链到它。评审拿命令找手册段落用这个;
    • 漂移:解析不到的字面按字面分组,带出现它的条目引用;
    • 计数放在 totals 里,截断砍不掉(和 views-and-notes 的空组计数同一做法);分页沿用视图的游标。

    同一个根、同样的请求给出同样的字节;可以按根摘要缓存。用一个约 2 万条目的合成根测时间,写进 README。

  3. 漂移是确定的事实:例如“这个根的命令树里没有 X,条目 Y 提到它”。是手册勘误还是缺陷候选,留给 Circle 或人判断,Hub 不判。
  4. 绑定和渲染:
    • 视图能作为运行输入绑定,照 facets 视图的写法;
    • get_nodes 读一个目标路径时,回答文字里列出链到它的条目:只列引用和一行摘要,不展开全文;有上限时写明总数。
  5. FAMX 产品包声明它的链接:
    • command_literals 链到 /commands,规范化照 K1 生产时用的规则;
    • 生产器的漂移警告改成按这份声明算,保证生产时和读时是同一个规则;
    • 包升小版本,重签。
  6. 测试:
    • 链接、反向查找;
    • 漂移分组和计数(截断时计数照样对);
    • 不认识的声明被拒绝;
    • 两次读字节相同;
    • 生产警告和读时视图对同一份合成手册给出同样的漂移集合。

第二步(K2 和 views-and-notes 合并以后,集成者通知)

  • 评审包绑定反向视图:用例引用的命令,取链到它的手册段落作线索,不作评审根据。
  • 回归范围列出两个构建之间漂移的变化。

完成后在终端里回报:提交号、测试数量、没做完或拿不准的地方。