知识库三项收口：向量-元数据对账 + 导入侧幂等 + 过期行向量清理入口

① 只读对账 tools/reconcile_knowledge_vectors.py
   按集合列出：孤儿向量 / 死向量 / 缺向量 / 重复正文 / 低信息量碎片 / 纯标题。
   关键口径：非数字 id（FAQ-0013 这类语义 id）是灌库脚本有意写进 Milvus 的，
   单独归类、不建议删；向量数取自 query 实际行数，不用 get_collection_stats
   （后者含已软删未 compaction 的行）。

② 导入侧幂等：同 source_file + 集合重传 = 覆盖上一版
   app/service/knowledge_ingest_service.py 新增 _supersede_previous_version：
   把上一版 active 行置为 expired，并逐行投 knowledge.vector_delete_requested
   （与本次入库同事务）。写入侧只认 active 而检索侧不看 status，旧向量不清掉
   会继续参与排序、和同题活块抢答。
   顺带修掉一个真 bug：改为先判 chunks 非空再下线 —— 否则传一份解析出 0 块的
   文档会把上一版下架、新版一行没写，这份文档在检索侧凭空消失。

③ 清理入口：POST /api/v1/knowledge/{knowledge_id}/vector-cleanups
   给历史上"被别的途径置为 expired、从未投过删除事件"的行补投向量清理。
   DELETE 对已过期行返回 404 的口径保持不变（重复删除静默成功会让调用方
   分不清"这次真下线了"和"早就过期了"），因此新开一个语义明确的端点：
   不存在 404 / 仍是 active 422（请改用 DELETE）/ 已 expired 200 并回传事件名。
   配套 tools/purge_expired_knowledge_vectors.py（默认 dry-run）批量驱动该端点。

文档：docs/演示用/知识库向量对账与清理-2026-09-15.md（含真机验证输出），
并对 docs/演示用/知识库问答诊断-2026-09-14.md 做两处更正 —— 实测孤儿向量 0 条、
那 175 行历史副本从来没有向量（不参与排序），当时的差额来自 get_collection_stats
把已软删行算进去。

新发现（未修，需业务拍板）：661 条向量里 451 条正文不到 40 字，是灌库时把
markdown 表格/标题切碎产生的碎片。「风险评估问卷怎么评分」实测前 4 名是 4 条
一模一样的 19 字碎片（gap 0.0024），真正 2828 字的答案排第 5 → 客服必然转人工。
属灌库切分缺陷，补内容救不了，也不应靠放宽 MIN_GAP 解决。

验证：pytest tests/unit tests/contract → 1500 passed, 2 skipped, 0 failed；
mypy app → 3 个错全在组员文件中（与本次改动无关）；ruff 本次改动文件 0 错。
真机端到端：重传 → 旧行 expired + 删除事件 published + 旧向量已从 Milvus 删除；
两个问句回归仍正常回答（r1到r5 gap 0.0766；申购确认 0.8453）。

tests/unit/service/test_knowledge_management_service.py

@@ -402,6 +402,59 @@ async def test_archive_key_comes_from_the_knowledge_row() -> None:
     assert storage.archived == ["kb/faq/deadbeef-faq.md"]
 
 
+# --- ④ 补投向量清理（expired 行） --------------------------------------------
+
+
+async def test_cleanup_vector_enqueues_delete_for_an_expired_row() -> None:
+    """已过期的历史行必须能补投删除事件——这正是 `DELETE` 覆盖不到的那批行。"""
+    row = meta_row(7, status=EXPIRED_STATUS)
+    service, session, _, _ = build_service(rows=[row])
+
+    result = await service.cleanup_vector(context(), 7)
+
+    assert row.status == EXPIRED_STATUS  # 不改状态：本动作只补投事件
+    events = delete_events(session)
+    assert len(events) == 1
+    assert events[0].aggregate_id == "7"
+    assert events[0].payload == {"knowledge_id": "7"}
+    assert events[0].trace_id == "trace-task11"
+    # 事件 id 必须是新的 uuid4：与历史事件同 id 会被 outbox 的唯一键吞掉，等于没投。
+    assert events[0].event_id
+    assert result == {"knowledge_id": 7, "status": EXPIRED_STATUS,
+                      "vector_delete_event": "knowledge.vector_delete_requested"}
+
+
+async def test_cleanup_vector_refuses_an_active_row() -> None:
+    """在用文档不得被"只删向量不标状态"：那会造成"行是 active、向量已没"的不一致。"""
+    service, session, _, _ = build_service(rows=[meta_row(7, status="active")])
+
+    with pytest.raises(ValidationAgentError):
+        await service.cleanup_vector(context(), 7)
+
+    assert delete_events(session) == []
+
+
+async def test_cleanup_vector_unknown_id_is_not_found() -> None:
+    service, session, _, _ = build_service(rows=[meta_row(7, status=EXPIRED_STATUS)])
+
+    with pytest.raises(GenericResourceNotFoundError):
+        await service.cleanup_vector(context(), 999)
+
+    assert delete_events(session) == []
+
+
+async def test_cleanup_vector_requires_the_management_permission() -> None:
+    service, _, _, _ = build_service(rows=[meta_row(7, status=EXPIRED_STATUS)])
+
+    def explode() -> None:
+        raise AssertionError("未授权请求不得打开数据库会话")
+
+    service._session_factory = explode  # type: ignore[assignment]
+
+    with pytest.raises(ForbiddenAgentError):
+        await service.cleanup_vector(context(permissions=()), 7)
+
+
 # --- 装配与路由 -------------------------------------------------------------
 
 
@@ -420,10 +473,12 @@ def test_router_registers_the_three_required_paths() -> None:
     assert ("/api/v1/knowledge/upload", "POST") in paths
     assert ("/api/v1/knowledge/list", "GET") in paths
     assert ("/api/v1/knowledge/{knowledge_id}", "DELETE") in paths
+    # 运维补口：给已过期的历史行补投向量清理。
+    assert ("/api/v1/knowledge/{knowledge_id}/vector-cleanups", "POST") in paths
 
 
 def test_every_endpoint_depends_on_the_authentication_gate() -> None:
-    """硬约束：三个端点都必须依赖 `build_request_context`，禁止匿名入口。"""
+    """硬约束：每个端点都必须依赖 `build_request_context`，禁止匿名入口。"""
     from app.api.controllers.knowledge_management import router
 
     for route in router.routes: