ragflow/internal/ingestion/component/knowledge_compiler/PORT_PLAN.md

将 rag/advanced_rag/knowlege_compile 移植到 Go 的计划

目标：在 internal/ingestion/component 下新增一个 pipeline 组件 KnowledgeCompiler， 把 Python 版「知识编译」全部变体（wiki / raptor / mind_map / structure / dataset_nav） 收敛到同一个组件，按 variant 参数分派。

评审缺口索引（code review 后补，正文以「缺口 X」标注）：

• 缺口 #1 历史去重决议（wiki 组件内 ES KNN + HistoricalCandidates 可选覆盖）→ §4 / 风险 #2
• 缺口 A 容量护栏（防 OOM）→ Param.Guardrails / §4 Outputs / M1 单测
• 缺口 C Raptor 验证门禁（NMI/ARI + 回退）→ M6 / 风险 #1
• 缺口 D 输出合约前置冻结 → §4.1
• 缺口 E golden 对齐必选门禁 → §6
• 缺口 F 变体命名主名 + alias → §4 Inputs

---

1. 范围与现状

Python 源（rag/advanced_rag/knowlege_compile/）

文件	职责	关键导出
_common.py	共享底座：stable id、embed 包装、tokenize、chunk 批处理引擎、bulk dedup（exact+embed+LLM）、ES I/O。 注意：Go 版删除「从 ES 拉源 chunk」与「组件内写 ES」，但保留 wiki 变体历史去重的 ES KNN 读路径（见 §1.1）；输入仍来自内存 inputs，产物以 chunks 形式合并进上游分块流返回	stable_row_id, encode, build_chunk_batches, run_chunked_pipeline, bulk_dedup_items（内存去重 + wiki 历史候选 ES KNN）
structure.py	文档级结构编译（list/set/hypergraph）+ 本地/ES 去重 + 紧凑图 JSON	compile_structure_from_text, merge_compiled_structures, rebuild_structure_graph_json
wiki.py	工件管线 MAP→REDUCE→PLAN→REFINE（最大，~3600 行）	wiki_map_from_chunks, wiki_reduce_from_extracts, wiki_plan_from_reduction, wiki_refine_from_plan
raptor.py	RAPTOR 摘要树：classic + Psi 两种 builder，GMM/AHC/UMAP 聚类	RecursiveAbstractiveProcessing4TreeOrganizedRetrieval
mind_map_extractor.py	基于 markdown_to_json 的心智图抽取	MindMapExtractor
dataset_nav.py	数据集级导航的增量聚类（nav_cluster / nav_doc 树 + Redis 锁）	upsert_dataset_nav_doc, remove_dataset_nav_doc
runner.py	非 tree 模板的批量编排（LLMCallPool、flush、synthesis 阶段）	run_structure_compile_over_batches

1.1 输入/输出/存储模型变更（关键，Go 版以内存为主 + wiki 历史去重读 ES）

Python 版 knowlege_compile 在运行时全程依赖 ES：先连 ES 把已切好的源 chunks 拉出来 （_common.py 的 es_search / MatchDenseExpr 取 doc_id 对应的 chunk 集合）， 编译过程中的去重/合并又回查 ES 里已写入的编译产物做 KNN 候选，最后把产物写回 ES。

Go 版是 pipeline 组件，以内存为主，并在 wiki 历史去重阶段读 ES KNN：

1. 输入来自内存：KnowledgeCompiler 的 Inputs() 直接消费上游 chunker/parser 输出的 chunks（每项带 id + text/content_with_weight 等）。删去「按 doc_id 去 ES 拉源 chunk」。
2. 编译产物驻留内存：所有编译产物（structure 图 / wiki page / raptor summary / mindmap tree / datasetnav 节点）在 Invoke 期间先存于内存结构中，组件不负责写 ES。
3. 落库由 pipeline 调用者负责：产物通过 Outputs() 返回给下游，由 pipeline 的 调用方（组合根 / 后续 writer 组件）统一决定何时、如何写入 ES。
4. 去重分两层：

• 运行内去重：在内存里已累积的编译产物集合中做向量相似检索（暴力余弦 / 小顶堆 top-k）；
• 历史去重（wiki 变体）：对 document 级 graph（entity/relationship）并行发起 ES KNN 候选检索， 作用域受 tenant_id + dataset_id + variant 过滤约束，命中后在组件内直接 merge。

结论：KnowledgeCompiler 组件保留 common/memstore.go（运行内去重）， 并为 wiki 变体新增只读 ES KNN 候选检索依赖（不在组件内写 ES）。 Deps 包含 Chat / Embed / Tokenizer，以及 HistoricalKNN（或 DocEngine.Search 只读封装，见 §3/§4）。

移植原则（遵循 AGENTS.md）

• 收敛为单一组件 KnowledgeCompiler，用 variant 参数分派，不保留 Python 的多文件分叉。
• 复用现有 runtime.Component 注册模式（参考 component/extractor.go）。
• 组件包 不得 反向 import internal/service；模型/引擎解析器在 internal/ingestion/task（组合根）注入，沿用 embedder.go 的 DefaultEmbedderResolver 模式。
• 优先用 Go 已有能力，缺失的才新增；不引入与现有 runtime 重复的兼容层。

---

2. 模块映射（Python → Go）

rag/advanced_rag/knowlege_compile/
├── _common.py          → knowledge_compiler/common/      (id, embed, tokenize, batching, dedup engine, in-mem store)
├── structure.py        → knowledge_compiler/structure/   (compile + merge + chain + graph json)
├── wiki.py             → knowledge_compiler/wiki/        (map / reduce / plan / refine)
├── raptor.py           → knowledge_compiler/raptor/      (classic + psi builders + clustering)
├── mind_map_extractor  → knowledge_compiler/mindmap/     (markdown→json tree)
└── dataset_nav.py      → knowledge_compiler/datasetnav/  (incremental nav clustering + redis lock)

runner.py 的编排逻辑（LLMCallPool / flush / synthesis）下沉为 knowledge_compiler/common 里的并发原语（信号量 + 优先级队列 + 批累积器）， 由 KnowledgeCompiler.Invoke 直接驱动，不再单独保留一个 runner 文件。

---

3. Go 基础设施依赖：现状与缺口

✅ 已具备

• Embedding：componentpkg.Embedder 接口 + EmbedderResolver + DefaultEmbedderResolver （internal/ingestion/task/embedder.go 已在 init() 注入）。
• Tokenizer：internal/tokenizer（C++ binding，含 tokenize / fine_grained_tokenize 等价能力）。 另需一个 num_tokens_from_string 等价函数（基于 tiktoken 或 RAG 分词器，放在 common 包）。
• DocEngine / 历史 KNN Reader（只读）：组件不写 ES，但 wiki 变体会在历史去重阶段读取 ES KNN 候选 （见 §1.1）。建议以 HistoricalKNN 接口封装 Search 能力，避免组件直接耦合全量 DocEngine。 输入 chunks 仍来自内存 inputs，写入 ES 与普通 chunk 走同一落库路径。
• Chat 工厂：models.NewModelFactory().CreateModelDriver(...) + models.NewEinoChatModel （extractor.go:einoExtractorChatInvoker 已示范）。
• xxhash：github.com/cespare/xxhash/v2（已在 go.mod，被 chunk_builder 等使用）。
• 组件注册：runtime.MustRegister(name, CategoryIngestion, ctor, Metadata{Inputs,Outputs})。

⚠️ 缺口（需新建，按风险排序）

1. JSON-mode chat helper（gen_json 等价物） —— 最高频依赖。 封装 einoExtractorChatInvoker：请求时带 response_format=json（或 JSON schema）， 返回解析后的 map[string]any / []any，带 code-fence 剥离、重试、超时。 建议新增 knowledge_compiler/common/jsonchat.go，复用 extractor 的 driver 解析与 invoker 注入 seam。
2. 内存产物存储 + 内存向量检索（common/memstore.go） —— 承担运行内去重（见 §1.1）。提供：
   • Add(item) / Upsert(id, item) / Delete(id)：维护本次 pipeline 内的编译产物集合；
   • TopK(vec []float32, k int, threshold float64) []Hit：内存余弦 top-k，供去重/合并做候选查找。 实现建议（见下方①）：内部把已存产物向量维护为一个 [][]float32 + 预计算的 L2 norm （embedder 若已归一化则可直接用点积）；TopK 对 query 做一次 matVec 取点积再阈值过滤 + 部分 top-k。单次 pipeline 规模不大，朴素循环也够，但走矩阵形态（gonum mat.Dense.Mul 或手写点积）更一致、更易与 RAPTOR Psi 的全对 M·Mᵀ 共用同一套向量运算。

• Snapshot() []Item：Invoke 结束时把全部产物交给 Outputs()，由 pipeline 调用者落库。

3. 历史去重 KNN 检索器（wiki 专用） —— 新增 common/historical_knn.go（或等价位置）：

• TopKHistory(ctx, qvec, k, threshold, scope) []Hit，scope 至少含 tenant_id/dataset_id/variant；
• 仅用于读取历史候选；命中后在组件内执行 merge（仍不在组件内写 ES）。

3. 聚类数值库（RAPTOR classic builder） —— Python 用 sklearn 的 GaussianMixture(BIC 选簇)、AgglomerativeClustering(ward + dendrogram gap)、umap.UMAP。 最终决策（M6 前已拍板）：纯 Go + gonum，不引入 pa-m/sklearn，不用 CGO/C++ 内核。

   放弃 pa-m/sklearn：它只是 sklearn API 的 Go 模仿版，不成熟，尤其 GMM/UMAP 支持残缺， 多一个需审计的第三方 ML 依赖得不偿失。 不用 CGO/C++ 内核（libcluster.so 之类）：本仓库 build.sh 已在 juggling CGO 原生库 （office_oxide / pdfium / pdf_oxide / lld），再加一个自维护 C++ 数值内核会显著加重构建与长期维护负担； 而本场景数值热度根本不需要它（见下）。 只加 gonum.org/v1/gonum（纯 Go、无 CGO，不影响 build.sh 的 CGO 链路）到 go.mod。

   关键事实（已核对 raptor.py 源码）：

   • clustering() 在分支之前无条件跑 umap.UMAP(metric="cosine") 降到 ≤12 维（raptor.py:326-333）， 所以即便只支持 AHC 也仍需降维器；Go 用 PCA（gonum mat.SVD，SVDThin） 替代 UMAP。 对文本 embedding（BGE/E5/...）PCA 通常保留大部分聚类结构，且比「cosine-UMAP→Ward」更契合 Ward 的欧氏几何。
   • Psi builder 完全不聚类（仅余弦矩阵 + union-find，raptor.py:425-432），零 GMM/AHC/UMAP 依赖。
   • GMM 是 covariance_type="diag" + reg_covar=1e-4（raptor.py:261,351），不是 full 协方差。 因此 EM 只需逐维均值/方差，无需 Cholesky / 全协方差行列式 / 逆矩阵 —— 实现量约 200-300 行， 远低于 full 协方差的 500-800 行；BIC 参数 p = K·d(均值) + K·d(对角协方差) + (K-1)(权重)，可直接算。 GMM 还用 predict_proba + threshold(默认 0.1) 软分配（取 prob>阈值 的首簇，否则 argmax）。
   • Ward AHC：维护 {centroid, size, SSE} 的 struct（cache locality 好），距离矩阵用扁平 []float64 连续内存（避免 [][]float64 反复分配）；典型 N=几千~几万、降维后 D≤12，O(n²) 距离矩阵完全可接受。 保存 merge history 即得到 linkage 矩阵 Z=[left,right,distance,size]，dendrogram gap = 排序后 heights 的差分 argmax。

   交付分解（M6）：

   • Psi builder：仅余弦矩阵（复用 ① 的 memstore 向量运算），零聚类依赖。
   • classic(AHC + PCA)：自写 Ward 链接 + gap 检测 + _adjust_tree_nodes(质心重分配，k-means 式)；PCA 走 gonum。
   • GMM/BIC + predict_proba 软分配：留 ClusteringMethod 可插拔接口，后补（纯 Go diagonal-GMM EM，已确认成本低）； 不在 M6 阻塞项。

   接口骨架（现在就定义，避免将来改 raptor.Run 签名） —— M6 落地前先把边界定死：

   // ClusteringMethod 标识聚类后端；M6 只交付 AHC，GMM 留 TODO。
   type ClusteringMethod string
   
   const (
       ClusteringAHC ClusteringMethod = "AHC"        // 默认：Ward + gap 检测 + _adjust_tree_nodes
       ClusteringGMM ClusteringMethod = "GMM"        // TODO(M6+): diagonal-GMM EM + BIC + predict_proba 软分配
   )
   
   // ClusterSpec 聚类配置，对应 Python RaptorConfig 的聚类相关字段。
   type ClusterSpec struct {
       Method      ClusteringMethod
       Threshold   float64 // AHC: dendrogram gap 阈值；GMM: predict_proba 软分配阈值(默认 0.1)
       MinClusters int     // _get_optimal_clusters 下界
       MaxClusters int     // _get_optimal_clusters 上界(默认 20)
   }
   
   // Clusterer 聚类后端接口；AHC/Psi 实现各自满足。
   // embeddings: 降维后矩阵 (n×d, d≤12)；返回每点簇标签 + 簇质心（供 _adjust_tree_nodes）。
   type Clusterer interface {
       Fit(embeddings [][]float64, spec ClusterSpec) (labels []int, centroids [][]float64, err error)
   }
   
   // Run 签名以 ClusterSpec 传入，后端按 Method 分派；GMM 未实现时返回明确 ErrNotImplemented。
   func Run(ctx context.Context, in *Inputs, spec ClusterSpec, deps Deps) (*Outputs, error)
   

   注：Psi builder 不走 Clusterer（仅余弦矩阵 + union-find），但 Run 仍以 ClusterSpec 统一入口， 内部按 Method/builder 分派到 Psi 或 classic 路径，保证签名单一、将来加 GMM 不破 Run。

4. markdown_to_json（mind_map）的 markdown 来源澄清 —— 注意它不是文档级也不是 chunk 级 的源 markdown，而是 LLM 的回答 markdown（mind_map_extractor.py:168 markdown_to_json.dictify(response)，response 是 MIND_MAP_EXTRACTION_PROMPT 产出的思维导图大纲； 输入 sections 只是喂给 LLM 的源文本，dictify 作用在模型输出上）。 因此不能复用 Go Parser 组件（parser.go/parser_dispatch.go）的输出——那是源文档解析结果，与本题无关。 Go 端用 goldmark 解析** LLM 回复的 markdown 大纲**，按 Python dictify 语义（标题层级→嵌套 dict、 列表项→数组）自实现轻量 AST 遍历转换即可；无需引入等价重库。计划措辞应改为「LLM 回复 markdown→tree」。

5. Redis 分布式锁 —— dataset_nav 用 RedisDistributedLock。 internal/engine/redis 已有 RedisClient，新增一个 spin_acquire/release（SET NX + TTL）封装即可。

6. 多语言 config localize —— Python 的 _struct_localize 取 cfg["en"] 等。 Go 端 common 加一个 localize(value any, lang string) string 处理 string / []string / map[string]string。

7. split_chunks token budget（注意含义） —— 它不读 ES/磁盘、也不切分单个 chunk， 而是把内存中的 chunks 按 LLM 上下文窗口做 token-budget 打包成 batch （generator.split_chunks:795 注释「Do not split a single chunk, even if it exceeds max_length」， 是 build_chunk_batches/run_chunked_pipeline 引擎里的预算装箱步骤）。既然 chunks 已在内存， 仍需要它来尊重 chat_mdl.max_length 的窗口约束。建议改名 split_chunks.go → batch_packing.go （或并入 batch.go），明确其语义是「内存 chunks → LLM 批次」，避免误读成「从外部切分加载」。

---

4. 组件接口设计

const componentNameKnowledgeCompiler = "KnowledgeCompiler"

// Param 由 DSL params 构造；缺失键走 Defaults()。
type Param struct {
    Variant          string // "structure" | "wiki" | "raptor" | "mindmap" | "datasetnav"
    LLMID            string
    EmbeddingModel   string
    Language         string // "en" / "zh" / ...
    TemplateIDs      []string // structure/wiki 用；group_ids 在 Invoke 时解析
    GroupIDs         []string
    SimilarityThreshold float64 // 去重阈值，默认 0.99(structure) / 0.9(artifact)
    MaxWorkers       int
    // 变体特有：raptor 的 max_cluster / tree_builder / clustering_method；
    //          wiki 的 synthesis example；mindmap 的 prompt 覆盖等
    Extra map[string]any

    // 历史去重开关：wiki 变体在 document graph 阶段并行读取 ES KNN 候选。
    EnableHistoricalDedup bool

    // 容量护栏（缺口 A，防 OOM/GC 抖动）：限制单次 Invoke 产物规模，见 §4 Outputs。
    Guardrails CapacityGuardrails
}

// CapacityGuardrails 单次 Invoke 产物容量上限；任一超限即触发对应处置（error / flush）。
type CapacityGuardrails struct {
    MaxItems       int         // 产物条目上限（默认按变体给安全值，如 structure 5e4、raptor 按树规模）
    MaxVectorBytes int64       // 向量总字节上限（= Σ len(vec)*4）
    MaxOutputBytes int64       // 全部产物序列化字节上限
    OnExceed       ExceedAction // "error" | "flush"
}

// ExceedAction 超限处置：error=返回 ErrCapacityExceeded；flush=经 ChunkedSink 分段交付。
type ExceedAction string

• 变体命名口径（统一主名 + alias，缺口 F）：组件内部 Param.Variant 与 Run 分派键一律用 structure / wiki / raptor / mindmap / datasetnav（无下划线，Go 风格）。 DSL 模板若填旧名 mind_map / dataset_nav，在 Param 构造处做 alias 映射 + 弃用日志 （mind_map→mindmap、dataset_nav→datasetnav），其余未知值返回明确 ErrUnknownVariant。 里程碑描述里的 mind_map/dataset_nav 仅为人读别名，代码与模板一律用主名。

• Inputs()：返回 chunks(直接来自上游 chunker/parser 的输出，每项带 id+text/content_with_weight， 见 §1.1，不再从 ES 读源 chunks)、llm_id(可选覆盖)、embedding_model(可选覆盖)、变体特有键。

  • HistoricalCandidates []Candidate(可选覆盖路径)：用于测试或离线模式；若未提供且 EnableHistoricalDedup=true，wiki 变体从 ES 并行检索历史候选（KNN）。 命中在组件内直接 merge（merge 统计仅留存于组件内部）。
  • Sink ChunkedSink(可选)：当 CapacityGuardrails.OnExceed=="flush" 时，组件边产边回调 分段交付，避免 Outputs() 一次性持有全部产物（缺口 A）。

• Outputs()：回传 chunks（与上游 chunker 输出 schema 完全一致）—— 各变体产物（structure 图行 / wiki page / raptor summary / mindmap tree / datasetnav 节点）转换为 schema.ChunkDoc（对齐 conf/infinity_mapping.json，以 compile_kwd 区分普通分块），与上游输入 chunks 合并后作为 Outputs() 的 chunks 返回；运行内去重/历史合并 统计不再外显到输出 surface（仅在组件内部 common.Outputs 中留存）。 容量护栏：若 Guardrails.OnExceed=="error" 且超限，Invoke 返回 ErrCapacityExceeded； 若 =="flush"，产物经 ChunkedSink 已分段交付。持久化与任何普通 chunk 一致，由调用方决定。

• Invoke(ctx, inputs)：解析 variant → 调 structure.Run / wiki.Run / raptor.Run / mindmap.Run / datasetnav.Run。每个子包暴露 Run(ctx, deps, param, inputs) (map[string]any, error)， 共享 common.Deps{ Chat ChatInvoker; Embed Embedder; Tokenizer; HistoricalKNN; ... }。 各 Run 内部用 common.MemStore 做运行内去重；wiki 变体额外并行调用 HistoricalKNN 做历史候选标记， 结束时 Snapshot() 进 outputs。

• init()：runtime.MustRegister(componentNameKnowledgeCompiler, runtime.CategoryIngestion, NewKnowledgeCompilerComponent, Metadata{...})。

依赖注入 seam（沿用 embedder 模式）

KnowledgeCompiler 不直接构造模型，而是持有一个 common.DepsResolver： 在 internal/ingestion/task 的 init() 里把生产 resolver 注入 （GetChatModel(tenantID, llmID)、DefaultEmbedderResolver、HistoricalKNNResolver； datasetnav 若需 Redis 锁再单独注入 RedisClient，见 §5 M8）。 测试时替换 resolver 注入 mock。组件仅执行历史候选读取，不在组件内写 ES；落库仍由 pipeline 调用者处理。

4.1 输出合约（chunk 对齐，缺口 D 演化）

组件不落库、也不再通过独立的 writer seam 写 ES：编译产物在 Invoke 期间驻留内存， 结束时转换为 schema.ChunkDoc（对齐 conf/infinity_mapping.json，以 compile_kwd 区分普通 分块），与上游输入 chunks 合并后作为 Outputs() 的 chunks 返回，schema 与上游 chunker 完全一致。行结构冻结项（M1 即与组件输出 schema 同步）：

• 行结构 schema：每条产物即一个 schema.ChunkDoc，含 id(xxhash 稳定)、doc_id/tenant_id、 text/content_with_weight、compile_kwd(=variant)、parent_kwd(树形变体)、q_<dim>_vec(向量)、 以及 kc_* 前缀保留原始 meta(kind/level/name/size)。
• 幂等键：(tenant_id, doc_id, variant, id) 唯一；若需落库，调用方以 upsert 语义写入，重复 id 覆盖不新增。
• 历史去重职责：wiki 变体在组件内执行并行历史候选检索 + 直接 merge（ES KNN 只读），merge 统计仅留存 于组件内部 common.Outputs，不再外显到输出 surface。
• 错误语义：容量超限(ErrCapacityExceeded)、未知变体(ErrUnknownVariant)、LLM/embed 失败均透传。

---

5. 分阶段实施

• M1 脚手架 + common 底座 knowledge_compiler/common/：id.go(xxhash 稳定 id)、embed.go(Embedder 包装)、 tokenize.go(tokenizer + num_tokens)、batch.go(build_chunk_batches + run_chunked_pipeline)、 memstore.go(内存产物存储 + 内存向量检索 Add/Upsert/Delete/TopK/Snapshot)、 localize.go、batch_packing.go(内存 chunks → LLM token-budget 批次，原 split_chunks)。 单测：mock Embedder + memstore 的 TopK 精度/阈值断言； 新增容量护栏单测（缺口 A）：注入超大 chunks 集，断言 CapacityGuardrails 的 error/flush 两条路径（ErrCapacityExceeded 与 ChunkedSink 分段回调次数），作为大文档内存压力的最小防护。

• M2 JSON chat helper + 并发原语 common/jsonchat.go（gen_json 等价：JSON 模式请求 + 解析 + 重试 + 超时）、 common/pool.go（LLMCallPool 等价：优先级信号量）。 单测：注入 canned JSON 响应。

• M3 structure 变体（编译 + 内存去重） structure/compile.go：compile_structure_from_text（list/set/hypergraph 提示词渲染、 hypergraph 的 node→edge 两阶段、产物行构造）、merge.go：merge_compiled_structures 的本地去重（余弦候选 + LLM merge-pair + 别名重写 relation 端点 + 紧凑图 JSON），全程走 common.MemStore。返回 docs 供断言。

• M4 structure 内存合并闭环 merge.go 接 memstore.go：内存 TopK 候选查找（替代 ES KNN）、分组 LLM 判定、 批量合并、rebuild_structure_graph_json，最终 Snapshot() 全部产物进 Outputs()。 单测用 memstore 双跑验证 inserted/updated/duplicates_dropped 计数（无需 DocEngine）。

• M5 wiki 变体 wiki/：map_from_chunks → reduce_from_extracts → plan_from_reduction → refine_from_plan，含 5 个 WIKI_*_COMPILE_KWD 与 synthesis 阶段（example + compile_kwd 覆盖）。 在 document 级 graph（entity/relationship）产出后，启用并行历史去重：内存 TopK + ES KNN 候选， 命中后组件内直接 merge 并写入统计（historical_merged）。

• M6 raptor 变体 raptor/：先交付 Psi builder（仅余弦矩阵，零聚类依赖） + classic(AHC + PCA 降维)； AHC 仍需降维器（见缺口 #3：clustering() 无条件先 UMAP，Go 用 gonum PCA 替代）。 聚类后端：Ward AHC + gap 检测 + _adjust_tree_nodes 全部纯 Go + gonum 自实现； GMM/BIC 留 ClusteringMethod 可插拔接口与 TODO（纯 Go diagonal-GMM，后补，不阻塞 M6）。 summarize_texts 走 jsonchat/普通 chat + embed。 验证门禁（缺口 C，替代原「保真度可接受」弱约束）：M6 落地前先跑 Python raptor.py 在固定样本集上 产出一个基线快照（簇标签、树高、叶覆盖、summary 文本），Go 版须对齐：

  • 指标：与基线对比 NMI/ARI（簇一致性）、平均/最大树高、叶节点覆盖率(≥基线 95%)；
  • 离线召回：固定 query 集的 top-k hit 率回退不超过设定阈值（如 5%）；
  • 门禁失败回退：classic(AHC) 任一指标不达标即禁用 classic、仅启用 Psi（Psi 零聚类依赖、风险更低）， 并告警，不阻塞发布。 （开放问题 3：需确认是否存在可固化的 Python/Go 聚类一致性回归样本集；若无，先用合成 embedding 构造。）

• M7 mindmap 变体 mindmap/：goldmark 解析 + dictify 语义转换 + 多段合并（_merge/_be_children）。

• M8 datasetnav 变体 datasetnav/：Redis 锁封装 + 分层 KNN 下降 + LLM merge/summary + 增量 split/rebalance。 单测用 miniredis 或内存锁。

• M9 注册 + 模板 + 集成测试 在 internal/ingestion/pipeline/template/ 新增一个使用 KnowledgeCompiler 的 pipeline DSL（或一个参数化模板按 variant 切换），下游接普通 chunk 落库路径（组合根 / ES 写入） （消费 KnowledgeCompiler 的 outputs 产物）；builtin_registry 自动加载； 编写端到端用例：断言组件 outputs 产物正确，落库交由 pipeline 层验证。

---

6. 测试与验证

• 每个子包单测：mockEmbedder、mockChatInvoker（返回固定 JSON）、common.MemStore（真实内存实现）。
• 包级运行（遵循 AGENTS.md，必须用 build.sh 以拿到 CGO/原生库）：

  bash build.sh --test ./internal/ingestion/component/knowledge_compiler/...
  

• 行为对齐（structure + wiki 为 CI 必选门禁；raptor/mindmap/datasetnav 为可选 golden）： 用同一组 chunks 跑 Python 与 Go，对比 compile_structure_from_text 产物行数量与 merge 后 inserted/updated 计数；wiki 额外对比 reduce/refine 关键阶段产物形状。未达标阻断合并。
• 不默认跑全量 go test；只跑本组件子树。

---

7. 风险与决策

1. 聚类保真度（最高风险）：sklearn GMM/UMAP 在 Go 无直接等价。 决策已定：纯 Go + gonum，不引入 pa-m/sklearn、不用 CGO/C++ 内核。
   • AHC 路径仍依赖降维（Python 分支前无条件跑 UMAP，raptor.py:326），Go 用 gonum PCA 替代； PCA 输出的欧氏空间更契合 Ward，保真度可接受，需在 M6 单测固化聚类数/阈值。
   • GMM 是 covariance_type="diag"（raptor.py:261,351），diagonal-GMM EM+BIC 约 200-300 行， 纯 Go 可行，留作可插拔后端后补，不阻塞 M6。
   • Psi builder 仅用余弦矩阵，不在此风险内。 结论：M6 先交付 AHC + Psi（AHC 走 PCA 降维；Psi 仅依赖余弦），GMM/UMAP 作为可插拔聚类后端后续补。 验证闭环见缺口 C：M6 须以 Python 基线快照做 NMI/ARI/树高/叶覆盖/离线召回门禁，失败则回退 Psi-only。
2. 历史去重一致性：Python 用 ES MatchDenseExpr（近似 KNN）在全量已存产物上查候选； Go 版改为「运行内 memstore 精确余弦 + wiki 历史 ES KNN 并行候选」。关键点：

• 运行内去重：MemStore.TopK 精确余弦；
• 历史去重（wiki）：HistoricalKNN.TopKHistory（ES 近似 KNN）按 tenant_id/dataset_id/variant 过滤；
• 历史命中后组件内直接 merge，落库幂等兜底由调用方负责。 结论：不再将其定义为“仅本次运行去重”的 breaking change；行为更接近 Python，但仍保留 enable_historical_dedup 开关用于灰度与回退。

3. 依赖方向：组件包不得 import internal/service；所有 resolver 在 internal/ingestion/task 注入。
4. 并发语义：Python 的 asyncio.Semaphore + 取消检查 → Go 用 context.Context + errgroup/信号量， 取消用 cancel_check 包成 ctx.Err() 检查。
5. 多语言/模板字段：config 的 en/zh 多语言与 entity/relation 新模板形状需完整映射， 避免只覆盖旧 output.entities/relations 形状。

---

8. 建议目录树

internal/ingestion/component/knowledge_compiler/
├── PORT_PLAN.md
├── component.go            // KnowledgeCompilerComponent + Param + Invoke + init 注册
├── deps.go                // Deps / DepsResolver 接口与注入 seam
├── common/
│   ├── id.go              // stable_row_id (xxhash)
│   ├── embed.go           // Embedder 包装
│   ├── tokenize.go        // tokenizer + num_tokens + localize
│   ├── batch.go           // build_chunk_batches + run_chunked_pipeline
│   ├── batch_packing.go   // 内存 chunks → LLM token-budget 批次 (原 split_chunks)
│   ├── memstore.go        // 内存产物存储 + 内存向量检索 (Add/Upsert/Delete/TopK/Snapshot；不碰 ES)
│   ├── historical_knn.go  // wiki 历史候选检索接口/实现（只读 ES KNN）
│   ├── jsonchat.go        // gen_json 等价
│   └── pool.go            // LLMCallPool 等价
├── structure/  (compile.go, merge.go, prompt.go, graph.go, chain.go)
├── wiki/      (map.go, reduce.go, plan.go, refine.go)
├── raptor/    (raptor.go, clustering.go, psi.go)
├── mindmap/   (mindmap.go, dictify.go)
└── datasetnav/(nav.go, lock.go, split.go)

---

9. 交付顺序建议（最小可用路径）

M1 → M2 → M3 → M4（structure 变体端到端可用） → M9 注册 + 模板（让 pipeline 能跑 structure） → 之后再按 M5/M6/M7/M8 逐个补齐 wiki / raptor / mindmap / datasetnav， 每补一个变体就扩展 Param.Variant 与对应 Run，保持单一组件、单一注册入口。

发布策略（回答开放问题 2）：推荐分阶段发布——M9 先只上线 structure 变体并默认启用； wiki/raptor/mindmap/datasetnav 经 feature flag 逐步放开，其中 raptor 的 classic(AHC) 受 M6 验证门禁约束（不达标则仅启用 Psi），避免低质量摘要树进入召回。