| name | cross-ref |
| description | 当需要在已转化的 wiki 页面之间建立交叉引用、发现跨维度关联、或生成综合分析时使用。ingest 的自然后续步骤。 |
Cross-Ref — 跨文档关联与综合
扫描已转化的 wiki 页面,发现跨维度、跨模块的关联,建立交叉引用链接。
前置条件
至少有 1 个维度的 wiki 页面已由 ingest 转化完成。
输入参数
| 参数 | 必填 | 默认值 | 说明 |
|---|
--project <name> | 是 | — | 项目名称,对应 {KB_DATA_ROOT}/wiki/<project>/ 目录 |
--kb-data-root <path> | 否 | data | 知识库数据根目录,所有路径基于此 |
输出
- 更新所有 wiki 页面的交叉引用部分
- 新增综合分析页面(跨维度的 synthesis 页面)
- 更新
{KB_DATA_ROOT}/wiki/<project>/overview.md
反模式
| 反模式 | 正确做法 |
|---|
| "cross-ref 应该在 ingest 阶段就做" | ingest 只负责维度内的归一化,cross-ref 是维度间的关联 |
| "交叉引用太多了,只保留核心关联" | 所有发现的关联都应记录,后续可以通过重要性过滤 |
| "综合分析不需要代码证据" | 所有综合分析必须引用具体的代码路径或 wiki 页面 |
| "cross-ref 只做一次就够了" | 新维度 ingest 后需要重新 cross-ref |
执行流程
- 扫描
{KB_DATA_ROOT}/wiki/<project>/ 下所有 wiki 页面
- 构建实体-概念映射表
- 发现跨维度关联(同一实体在不同维度的描述)
- 发现跨模块关联(不同模块之间的隐式依赖)
- 为每个关联生成双向链接
- 识别需要综合分析的主题
- 按合成模板生成综合分析页面
- 更新 overview.md
关键原则
- 双向链接: 关联必须双向标注
- 证据驱动: 每个关联必须有代码或文档证据
- 增量更新: 新维度后需重跑 cross-ref