docs(celery Wave 7 §K.12): legacy graphindex 全删 + LightRAG 风格 graph 层最终态 spec

[earayu]

Summary

Wave 7 完整 spec — 删除整个 legacy graphindex 包 + 接通 LightRAG 风格语义召回 + UI 实体合并 + kg.jsonl 阶段自动检测合并候选。这是 graph + index 层最后一波修改。

per earayu2 msg=3d3b2e68 directive "最后一波 graph 和 index 层修改"，团队自驱 ship 1.5-2 周。架构师 @符炫炜 主导 + 辅助架构师 @huangheng review。

§K.12 sub-section coverage

• K.12.1 现状分析（grep 验证：legacy 包 + 隐藏功能性回归 + 已有 vector abstraction）
• K.12.2 四层分离设计哲学（图数据 / 向量 / 用户意图 / 候选检测）
• K.12.3 核心组件（GraphSearchService / GraphCurationService / GraphIndexCompactor / MergeCandidateDetector / GraphModalityWorker 扩展）
• K.12.4 schema 改动（compacted_description + alias_map + merge_candidate 表 + 老表 drop）
• K.12.5 DB column 长度防护（per-part 5K / per-entity 100 / unified 8K / truncate-not-fail）
• K.12.6 MCP 接口（3 tools）
• K.12.7 4 项决策 locked（D-3 + X + α + VectorStoreConnectorAdaptor）
• K.12.8 10 项 acceptance items + 1.5-2 周 ETA
• K.12.9 Pre-check pattern lock
• K.12.10 命名约定（去 LightRAG）
• K.12.11 Architect direct ratify lane
• K.12.12 close-out gate + 完成态

Test plan

• §K.12 spec text 完整覆盖 12 sub-sections
• 与 §K.11 Wave 6 spec amend 一致（chunk 2/3 ruling 引用）
• grep 验证现有 VectorStoreConnectorAdaptor 抽象可用（msg=ccfc6114 + huangheng msg=f1e695a0）
• earayu2 6 大 directive 全 honored（vector abstraction / 去 LightRAG 命名 / 老算法保留 / description 长度治理 / DB 列防护 / kg.jsonl 候选检测）
• huangheng 辅助架构师 review
• PM 派活后 implementer 起步

实施 dispatch

完整 spec 写好后，architect 在每个 task thread 内给详细上下文 + 实现指引。task #1-10 已由 PM 创建。

🤖 Generated with Claude Code

[earayu]

huangheng 辅助架构师 review，对照 v2 spec 12 architecture invariant + earayu2 msg=421c4223 6 项 correction 全过 → LGTM ✅，1 个 wording clarify + 3 个 fix-forward suggestion 非阻塞

12 invariant cross-check

#	Invariant	Spec 落点	状态
1	L1 写入幂等 (Wave 4 §C.3 契约)	§K.12.2 表 + §K.12.1.2 reference	✅
2	L1 → L2 单向派生	§K.12.2 lifecycle 表 invariant 段	✅
3	upsert_entity 内透明 alias redirect	§K.12.8 item 6 "chunk 2 critical inseparability" + §K.12.11 architect direct ratify	✅
4	vector 走 VectorStoreConnectorAdaptor 不锁 backend	§K.12.3 GraphSearchService/Curation/Worker 均显式 + §K.12.7 决策 4 lock	✅
5	Compactor 在 sync 末尾、vector embed 之前	§K.12.3 GraphModalityWorker.sync() 末尾四步顺序：1. Compactor → 2. embed/upsert → 3. snapshot-diff → 4. Detector	✅ 顺序正确
6	snapshot-diff 删除路径	§K.12.3 worker step 3 + §K.12.1.1 _delete_removed_shadow_vectors reference	✅
7	alias_map orphan persist (canonical gc 不级联删 alias)	§K.12.7 决策 X lock	✅
8	Detector 仅写候选不自动合并	§K.12.3 detector 段 explicit + §K.12.7 决策 K2 lock	✅
9	命名 grep-zero LightRAG	§K.12.10 lock 表，唯一例外是 §K.12.1 现状分析允许"灵感来自"	✅
10	DB 列长度安全	§K.12.4 TEXT NULL + §K.12.5 application-layer caps	⚠️ wording 见下
11	MCP tool 注册到 agent_runtime registry	§K.12.6 explicit + §K.12.8 item 7	✅
12	legacy 包删除是最后一步	§K.12.8 item 10 "依赖前 9 项全 merged" + §K.12.11 + §K.12.12 close-out gate	✅

earayu2 msg=421c4223 6 项 correction 验证

• ✅ 统一 vector store 抽象层（不锁 Qdrant）→ §K.12.7 决策 4 + §K.12.1.5 已有 VectorStoreConnectorAdaptor 复用
• ✅ 去 LightRAG 命名 → §K.12.10 lock 表 + §K.12.3 全用 GraphSearchService / GraphCurationService / GraphIndexCompactor
• ✅ 保留好的 legacy 算法 → §K.12.1.1 列出 6 个 method (_compact_oversized_descriptions / _summarize_description / _fallback_truncate / _should_summarize / _sync_entity_relation_vectors / _delete_removed_shadow_vectors)，§K.12.8 item 2/3 显式移植
• ✅ description 长度治理 → §K.12.3 GraphIndexCompactor + §K.12.5 + §K.12.8 item 2
• ✅ DB 列长度安全 → §K.12.5（见下 wording note）
• ✅ kg.jsonl 阶段自动检测合并候选 → §K.12.3 GraphModalityWorker step 4 + Detector 综合 string + vector + LLM judge

1 个 wording clarify（非阻塞，merge 前最好澄清；merge 后 fix-forward 也行）

§K.12.5 header "DB column 长度防护" 容易被 implementer (Bryce in task #1) 误读为 schema 层 CHECK constraint。实际表内 4 行约束都是 application-layer caps：

• per-part 5000 chars → graph_extractor 生成 kg.jsonl 时 truncate（不是 description_parts.text 列上 LENGTH check）
• per-entity 100 parts → Wave 6 P5A graph_extractor knob，不是 schema 层
• unified 8000 chars → GraphIndexCompactor + GraphCurationService 写 compacted_description 时控制
• truncate + log warn → application logic

而真正的 schema 列类型（§K.12.4）是 TEXT NULL (Postgres) / STRING (Neo4j) / string (Nebula) — 都是 unbounded。建议把 §K.12.5 header 改成"长度防护 (application-layer caps)"或加一句 prefix "schema 层不强制 cap，application 层负责防护"，避免 Bryce 给列加 LENGTH check 多此一举（task #1 thread 我已对齐 Bryce 的"列不强制 cap"理解）。

补一点：5000 chars per-part 来源标注 "Nebula tag-prop string 限制兼容" — 我理解 Nebula STRING 实际无 hard cap（FIXED_STRING(N) 才有），单 prop 写入 64MB 限。建议改成 "保守 cap，避免 Nebula tag-prop oversize warn / 跨 backend embedder 输入控制"，更准确。

3 个 fix-forward suggestion（不影响本 PR merge）

1. §K.12.5 per-part 5000 chars 的 enforcement layer 没指明 — 建议在 spec 加一句 "在 graph_extractor 层 truncate（kg.jsonl 生成时一次完成），后续 compactor 不重复 enforce"，避免 implementer 在 GraphIndexCompactor 里也 enforce 一次造成 double-truncate。

2. §K.12.3 GraphCurationService alias_map cycle flatten 算法没展开 — 当用户 merge A→C 之前已存在 B→A，需要 flatten 成 B→C, A→C 永远 1-hop。这是 item 6 inseparability 的子细节；spec 给了原则，implementer 在 item 6 PR 写清楚算法 + test "merge B→A 后 merge A→C → 验证 B 直接指向 C 不经过 A"。

3. §K.12.9 Pre-check pattern 没强制 paste 到 PR description — 三类 grep（caller import / state binding / Protocol method state）是好的 self-audit 工具，但如果 implementer 不主动 paste 输出到 PR body，huangheng + architect 都验证不到执行。建议 fix-forward：在 PR template 加一段 "## Pre-check matrix" 让 implementer 必填 grep 输出（mirror Wave 6 §K.11 close-out 模式）。

Architect direct ratify lane（§K.12.11）确认我理解一致

• 我（huangheng）做 pass-1 lane on items 1/2/3/4/7/8/9（小 bounded scope）
• Architect direct ratify on items 5/6/10（critical-path）
• 我对全部 10 PRs 主动 CR（不 gate-blocking，但飞 invariant drift / scope creep 时 surface 给 architect）
• 与 Wave 6 §K.11 lane lock 模式一致 ✅

Bryce task #1 thread 3 个问题中 Q1（entity vs entity+relation）已被 §K.12.4 lock

§K.12.4 明确写 aperag_lineage_entity + aperag_lineage_relation 都加 compacted_description: TEXT NULL，与 Bryce 倾向一致 ✅。Bryce 在 task #1 thread 可以解锁继续。

---

结论：spec 对架构 invariant 100% honor，对 earayu2 6 项 correction 100% honor，naming clean，决策 lock。可以 merge 让程序员开工。1 个 wording 建议 + 3 个 fix-forward 都可以放后面 §K.12 spec amend 一起处理（或本 PR push 一个 small follow-up commit），不阻塞。

@符炫炜 你 confirm wording fix 是 inline amend 还是 fix-forward，我没意见。