# 数据治理知识库 K6 验收记录

- 代码分支：`codex/knowledge-base-implementation`
- 实施计划：`docs/superpowers/plans/2026-07-20-llamaindex-lightrag-knowledge-base.md`
- 验收日期：2026-07-23
- 验收数据库：独立 PostgreSQL 数据库 `dataops_knowledge_20260723`
- 结论：首个可运行实施切片及本地工程验收完成；标准检索是主链路，LightRAG
  保持影子投影，其失败不会阻断 canonical 激活。生产 K6 发布门禁尚未批准。

## 完成范围

### 知识点级动态更新

- 使用稳定 `point_key` 和递增 `point_revision` 保存知识点版本，不做覆盖更新。
- 对序列化后的源版本执行结构化 Diff，区分新增、修改、删除和未变知识点。
- 依赖传播限定在已登记的确定性依赖边界内，避免无界重建。
- `prepare / validate / activate` 在 PostgreSQL 事务中发布 canonical 版本。
- 发布后按知识点依赖精确失效缓存；LightRAG 投影异步执行，可显示
  `projecting` 或 `degraded`，不回滚已验证的 canonical 版本。
- 支持 change set 重试、审计和回滚；回滚生成新的受控发布动作，不修改历史记录。

### 检索与问答

- LlamaIndex 负责标准节点映射和检索编排，PostgreSQL/pgvector 保存 canonical
  分块与向量。
- 精确、词法、向量、治理关系和 LightRAG 检索器采用统一证据契约，使用 RRF
  融合并显式报告降级组件。
- 权限和业务域过滤在检索 SQL 中前置执行，不在生成答案后补做脱敏。
- DeepSeek 问答只能使用已检索证据；证据不足时返回 `no_answer`，引用必须能回溯
  到对象 UID、对象版本、知识点修订和索引 generation。
- LightRAG 使用独立数据库、独立 Neo4j、固定 workspace、内部 API Key、稳定幂等键
  和熔断器，通过 Docker profile `knowledge-shadow` 启用。

### API 与页面

- 用户接口：`search`、`ask`、来源当前版本、来源指定版本和能力状态。
- 管理接口：同步状态、change set 明细/重试/回滚、审计、投影重试和评测结果。
- 页面覆盖问答/检索模式、可信边界、来源版本、freshness、空状态、降级状态和管理员
  索引状态；窄屏下平台侧栏自动收缩为图标栏。

## 验证结果

### 全量后端回归

```bash
PYTHONPATH=. TEST_DATABASE_URL=postgresql://.../dataops_knowledge_20260723 \
  .venv/bin/pytest -q
```

结果：`333 passed, 21 skipped, 59 subtests passed`。

覆盖内容包括：

- 知识点构建、Diff、依赖影响、分块、发布、缓存失效和同步状态机；
- PostgreSQL 真实事务中的原子版本切换、单知识点增量向量重算和回滚；
- PostgreSQL 真实词法检索、pgvector 检索和业务域前置过滤；
- LlamaIndex 节点映射、检索路由、RRF、LightRAG 客户端/投影/降级；
- 提示注入防护、证据不足、伪造引用拒绝和模型超时；
- API 契约、RBAC 权限矩阵和评测门禁。

### 数据库迁移与一致性

- 在空的独立数据库上执行全部 Alembic migration 至 head：通过。
- migration 后执行完整测试：通过。
- 测试后 canonical 一致性审计：`0` 个差异。
- 共享 `dataops` 数据库未被修改。

### 前端与浏览器

- `npm --prefix frontend run build`：通过；只有仓库原有的 21 个 `no-console`
  警告、CSS 顺序提示和 bundle 体积提示，没有新增编译错误。
- 使用生产构建、真实 Flask API 和独立 PostgreSQL 完成浏览器验收：
  - 管理员账号登录和菜单路由通过；
  - 能力状态和管理员同步状态加载通过；
  - 无 Qwen 凭据时，检索明确显示 `vector` 降级并返回可信空状态；
  - 无有效证据时，问答显示“不生成推测性答案”，引用数为 0；
  - 390 × 844 窄屏下侧栏收缩、内容正常重排；
  - 最终浏览器控制台：`0 errors, 0 warnings`。

### 静态与部署检查

- 新增和受影响 Python 文件 Ruff：通过。
- `git diff --check`：通过。
- `pip check`：通过。
- `docker compose --profile knowledge-shadow config --quiet`：通过。
- LightRAG 镜像使用固定 digest；sidecar 和其 Neo4j 不暴露主机端口。

## 外部联调边界

本地验收环境未配置真实 Qwen Embedding、DeepSeek 和 LightRAG 模型凭据，因此未产生
外部模型计费调用。模型适配、错误降级、引用约束和 LightRAG 投影协议已由自动化测试
覆盖；生产启用前仍需在受控测试租户补做一轮带真实凭据的离线评测和影子投影观察，
达到实施计划中的 Recall、MRR、引用正确率、越权率和 freshness 门禁后再提升流量。

此外，以下属于生产接入和发布阶段，不以本次本地验收代替：

- 将五类治理对象的所有写路径统一接入 source-revision Outbox 事件和单一知识消费者；
- 扩充并评审 150～300 条真实黄金问题集及 30～50 条时序变更集；
- 按业务域建立独立 LightRAG workspace，完成真实 insert/query/delete 残留验证；
- 执行带真实模型的离线评测、Canary、紧急撤销 SLA 和生产回滚演练。