---
name: xskill-registry-db-first
description: >-
  XSkill 数据访问原则：文件系统是内容真相，由 worker 同步进库；面板与业务读
  请求只走数据库；内核 agent loop 可直接写盘。适用于改 dashboard、recommend、
  team、pipeline、ecosystems 等读路径，以及审查是否又引入业务侧扫盘。
---

# XSkill 盘与库

改读数据相关代码，或审查业务请求是否又在扫盘时，先看本 skill。

各库职责与每张表的 schema 见 [databases.md](databases.md)。

## 架构

整体分三层。

文件系统存内容真相，例如 skill 目录里的文件。这些内容不会在每次面板请求时被重新扫描聚合。

有 worker 定期把文件系统上需要给业务侧查询的信息同步进 SQLite。同步可以按文件是否变化做增量。新的「盘到库」需求应并进已有扫描过程，而不是再开一轮同等规模的全量遍历。

面板、对外 API、推荐与其它业务读请求，一律通过数据库访问投影后的数据。业务侧不自己搭扫盘逻辑去凑结果。

内核里的 agent loop 在跑管线时可以直接读写文件系统，这是写真相的一侧，与业务读路径分开。

## 规则

业务面新增或修改请求时，所需数据从对应数据库取。不允许在业务请求路径里私自增加扫盘、全目录遍历、按请求反复读盘聚合。

若发现库与盘不一致，应修同步入口，而不是在查询里临时扫盘兜底。

若有新的文件系统到数据库的同步需求，去改现有的扫描同步 worker，把新投影挂进同一次遍历。不要为每个新需求再加一轮 N 加一的全量扫盘，以保持 IO 可控。

新建业务库前先查 [databases.md](databases.md)。已有库能覆盖的，不要平行再造一套真相。

多实例或独立 home 访问库时，路径要显式，避免误连全局默认库。

## 检查

1. 这次读的数据属于哪一个库？见 [databases.md](databases.md)。
2. 改的是业务读路径，还是内核写盘 / worker 同步？三者不要混用扫盘策略。
3. 若要加盘到库同步，是否已并进现有 worker 的同一轮扫描？
4. PR 是否在面板或 API 热路径新增了扫盘？有则打回。