任务:读时解析手册里的命令字面,给出交叉链接和漂移视图(K1 的后续)
依据:
- K05 R[2]:按路径路由加精确匹配检索,不用向量库(
node tools/show-element.ts K05 K01 K02)。 - K1 的 README(
packs/product/famx/README.md436–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/**。
第一步
- 产品包声明链接:product@1 的知识声明加
links,写明三件事:- 从条目 data 的哪个字段取字面;
- 链到哪个命名空间;
- 字面怎么变成路径:按空白切成词,一个词一段;规范化只许声明的几种,没有就照原样。
核心照声明做,不认识的声明整份拒绝。
- 读时视图:对锁定的根,按声明把每个条目的字面解析成目标路径。精确匹配到存在的节点算链接,没有的算漂移。视图给出:
- 正向:某个路径前缀下的条目链到哪些目标路径;
- 反向:给一个目标路径,哪些条目链到它。评审拿命令找手册段落用这个;
- 漂移:解析不到的字面按字面分组,带出现它的条目引用;
- 计数放在
totals里,截断砍不掉(和 views-and-notes 的空组计数同一做法);分页沿用视图的游标。
同一个根、同样的请求给出同样的字节;可以按根摘要缓存。用一个约 2 万条目的合成根测时间,写进 README。
- 漂移是确定的事实:例如“这个根的命令树里没有 X,条目 Y 提到它”。是手册勘误还是缺陷候选,留给 Circle 或人判断,Hub 不判。
- 绑定和渲染:
- 视图能作为运行输入绑定,照 facets 视图的写法;
- get_nodes 读一个目标路径时,回答文字里列出链到它的条目:只列引用和一行摘要,不展开全文;有上限时写明总数。
- FAMX 产品包声明它的链接:
command_literals链到/commands,规范化照 K1 生产时用的规则;- 生产器的漂移警告改成按这份声明算,保证生产时和读时是同一个规则;
- 包升小版本,重签。
- 测试:
- 链接、反向查找;
- 漂移分组和计数(截断时计数照样对);
- 不认识的声明被拒绝;
- 两次读字节相同;
- 生产警告和读时视图对同一份合成手册给出同样的漂移集合。
第二步(K2 和 views-and-notes 合并以后,集成者通知)
- 评审包绑定反向视图:用例引用的命令,取链到它的手册段落作线索,不作评审根据。
- 回归范围列出两个构建之间漂移的变化。
完成后在终端里回报:提交号、测试数量、没做完或拿不准的地方。