Xskill Registry DB First

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

SkillNerds Updated

File contents

XSkill 盘与库

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

各库职责与每张表的 schema 见 databases.md。

架构

整体分三层。

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

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

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

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

规则

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

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

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

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

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

检查

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

SkillNerds/xskill/tree/main/.agents/skills/xskill-registry-db-first commit 9761c7a04f

Frequently asked questions

npx skillmds@latest add skillnerds/xskill-registry-db-first