# `packages/kb/` — 美学知识库

**职责**（架构 §4.1）：知识实体/关系/规则/素材的读写与发布。
**不负责**：检索算法（调 `packages/retrieval`）。

## 本批已落地（T6，T-P2-01/05）

- `schemas.py`：12 类 `EntityType` Literal、`EntityStatus`、CRUD 与图谱
  响应模型（雪花 ID 一律字符串出参，防 JS 精度丢失）
- `repo.py`：`kb_entity`/`kb_relation`/`kb_color` 数据访问；
  `traverse` 为递归 CTE 1~3 跳有界遍历（防环：`path` 数组 + `NOT @>`）
- `service.py`：状态机（draft→reviewing→published→archived，撤稿支线
  draft/reviewing→archived，非法跃迁 40900）、内容修改 version+1 且
  published 只读（要改必须撤稿归档后重录新草稿）、关系写入（自环/重复/
  端点缺失校验）、色板 role/hex（`#RRGGBB`）校验
- 路由 `apps/api/routers/kb.py`：`GET/POST /kb/items`、
  `GET/PATCH /kb/items/{id}`、`GET /kb/items/{id}/graph?max_hops=1..3`

## 待实现（后续批次）

- `kb_rule` 决策表 CRUD（T7 规则引擎）
- `kb_chunk` 向量+全文混合检索（T8）
- `kb_asset` 白底图流水线、`kb_gap` 知识缺口埋点（T-P2-06+）
- 关系/色板的运营 HTTP 入口（后台角色 T-P2-09 就绪后挂路由）

## 为什么它是数据不是代码

架构 §1.1：**知识库是持续演进的资产，更新频率远高于代码**。规则、色板、单品
必须是数据，配顾问能独立使用的运营入口（FR-ADM-02），改内容不发版。
任何时候想把规则写成 `if` 分支，都是错的。

## 知识库版本号

所有检索缓存键都带全局 `kb_version`，发布时 +1，**旧缓存自然失效**
（架构 §10）。不要试图精确追踪哪些缓存受影响。