# Xskill Registry DB First

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

- Skill: `skillnerds/xskill-registry-db-first` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add skillnerds/xskill-registry-db-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/skillnerds/xskill-registry-db-first/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: SkillNerds (https://skillmd.com/u/skillnerds)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/skillnerds/xskill-registry-db-first

---


# 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 热路径新增了扫盘？有则打回。